Skip to content

first-run-cli.md

Latest commit

 

History

History
202 lines (138 loc) · 4.64 KB

first-run-cli.md

File metadata and controls

202 lines (138 loc) · 4.64 KB
Raw

First run (terminal / jz)

Run JoyZoning without the desktop — same governance rules, scriptable interface.

Familiar pattern: Like gh pr create or docker compose up talking to a local daemon.

Prerequisites: installation.md (control plane; diet-hermes only for managed task run)

Cursor-only? Skip Hermes gateway steps below. Use external-agent JSDP — you still need the control plane and jz.

Architecture (one picture)

jz  →  http://127.0.0.1:9470  →  SQLite + orchestrator
              ↓
         hermes -p joyzoning gateway  →  :8642 / :9119

The control plane must be running before jz commands (desktop auto-starts it; CLI-only users start it manually).

One-time setup

1. Shell environment

Add to ~/.zshrc (recommended):

export DOTNET_ROOT="${DOTNET_ROOT:-$HOME/.dotnet}"
export PATH="${DOTNET_ROOT}:${PATH}"
export JOYZONING_URL="${JOYZONING_URL:-http://127.0.0.1:9470}"
export JOYZONING_DIET_HERMES_DIR="${JOYZONING_DIET_HERMES_DIR:-$HOME/Downloads/diet-hermes-main-master}"

Or per session:

source /path/to/JoyZoning/scripts/jz-env.sh

2. Install CLI

cd JoyZoning
./scripts/install-jz.sh

You should see: Installed: ~/.local/bin/jz

Note: jz is a small wrapper script; the .NET app lives in ~/.local/bin/joyzoning-jz/. Do not replace the binary with the wrapper manually.

3. Start control plane

export ASPNETCORE_ENVIRONMENT=Development
cd JoyZoning
dotnet run --project src/JoyZoning.ControlPlane/JoyZoning.ControlPlane.csproj

Leave this terminal open.

4. Start Hermes gateway

"$JOYZONING_DIET_HERMES_DIR/.venv/bin/hermes" -p joyzoning gateway

Optional dashboard (kanban sync):

hermes -p joyzoning dashboard --no-open --tui

Or: curl -X POST http://127.0.0.1:9470/api/hermes/ensure-dashboard

5. Doctor

jz doctor

You should see:

{"ok": true, "checks": [
  {"id": "control_plane", "status": "ok"},
  {"id": "hermes_api", "status": "ok"}
]}

Your first session and task

# Bind to a project folder (like opening a folder in VS Code)
SESSION=$(jz --field .id session create \
  --name "cli-first-run" \
  --workspace "$HOME/src/myrepo")
export JOYZONING_SESSION_ID="$SESSION"

# Create a low-risk task
TASK=$(jz --field .id task create \
  --title "CLI smoke test" \
  --description "Prove jz wiring" \
  --risk 1)
echo "TASK=$TASK"

You should see: UUIDs printed; no stderr errors.

Start work (pick one)

Managed — Hermes lease

jz task run "$TASK" --poll 10 --timeout 600

You should see: JSON status transitions (leased → running → …).
If Hermes is down: exit 1 and JSON message on stderr — start gateway.

External — Cursor / manual (no lease)

jz task start-external "$TASK" --agent cursor
jz task prompt "$TASK"
# edit on joyzoning/card-* in your workspace
jz task mark-ready "$TASK"

See external-agent-jsdp.md.

Verify and merge (human-only complete)

jz task verify "$TASK" --cmd "echo ok"
jz task complete "$TASK" --yes

You should see: Task reaches Complete only after --yes merge.

Agents use jz agent done → ready_for_review, not Complete. See cli.md.

Agent harness (inside worktree)

After dispatch:

WORKTREE=$(jz --field .worktreePath task lease "$TASK")
cd "$WORKTREE"
jz agent start --task "$TASK"
jz agent verify --cmd "dotnet build"
jz agent done
# You still run: jz task complete "$TASK" --yes

Examples: scripts/examples/agent-happy-path.sh

CLI vs desktop feature map

Desktop CLI equivalent
Getting Started health jz doctor
Open workspace session create --workspace
Kanban dispatch task run
Cursor / external start task start-external · task prompt · task mark-ready
Merge button task complete --yes
Copy health report jz raw GET api/health + curls

Troubleshooting CLI-first

Symptom Fix
Session required export JOYZONING_SESSION_ID=...
.NET 8 missing DOTNET_ROOT — installation.md
cannot execute binary file Re-run ./scripts/install-jz.sh
Hermes API warn in doctor Start gateway; hermes-setup.md

Next

← Onboarding hub