# CLI

The JCode CLI lets you manage agents from your terminal. It's the same interface exposed by the daemon's API, so anything you can do in the app you can do from the command line.

> **Agent orchestration:** You can tell coding agents to use the JCode CLI to spawn and manage other agents. JCode recognizes the calling agent, so CLI-created workers get the same workspace and parent defaults as MCP-created workers.

## Quick reference

```bash
jcode run "fix the tests"            # Start an agent
jcode ls                             # List running agents
jcode attach <id>                    # Stream agent output
jcode send <id> "also fix linting"   # Send follow-up task
jcode logs <id>                      # View agent timeline
jcode stop <id>                      # Stop an agent
```

## Running agents

Use `jcode run` to start a new agent with a task:

```bash
jcode run "implement user authentication"
jcode run --provider codex "refactor the API layer"
jcode run --background "run the focused test suite"
jcode run --isolation worktree --base main "implement feature X"
jcode run --workspace <workspace-id> "review the current diff"
jcode run --output-schema schema.json "extract release notes"
jcode run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "summarize release notes"
```

From a human shell, a bare `jcode run` creates a new local workspace for the current directory. Use `--workspace <id>` to add the agent to an existing workspace, or `--isolation worktree` to create a new workspace backed by an isolated git worktree.

When an existing JCode agent runs the same command, JCode recognizes it through `JCODE_AGENT_ID`. Without explicit placement, the new agent becomes its subagent in the same workspace. `--workspace` can place that subagent elsewhere without changing its parent.

Use `--output-schema` to return only matching JSON output. You can pass a schema file path or an inline JSON schema object. This mode cannot be used with `--background`.

By default, `jcode run` waits for completion. Use `--background` to return immediately while the agent keeps running.

## Workspaces

Create a workspace independently when you want to prepare its files before starting an agent:

```bash
jcode workspace create --isolation local --path ~/dev/my-app --title main

jcode workspace create \
  --isolation worktree \
  --path ~/dev/my-app \
  --mode branch-off \
  --new-branch feature/auth \
  --worktree-slug feature-auth \
  --base main

jcode workspace create \
  --isolation worktree \
  --path ~/dev/my-app \
  --mode checkout-branch \
  --branch feature/existing \
  --worktree-slug existing-copy

jcode workspace create \
  --isolation worktree \
  --path ~/dev/my-app \
  --mode checkout-pr \
  --pr-number 2186
```

Then list, use, or archive it:

```bash
jcode workspace ls
jcode run --workspace <workspace-id> "implement authentication"
jcode workspace archive <workspace-id>
```

Add `--forge <name>` to PR checkout when JCode cannot infer the forge from the source checkout. See [Git worktrees](/docs/worktrees) for setup hooks and services.

## Listing agents

```bash
jcode ls                    # Running agents in current directory
jcode ls -a                 # Include completed/stopped agents
jcode ls -g                 # All directories
jcode ls -a -g --json       # Full list as JSON
```

## Streaming output

Use `jcode attach` to stream an agent's output in real-time:

```bash
jcode attach abc123   # Attach to agent (Ctrl+C to detach)
```

Agent IDs can be shortened, `abc` works if it's unambiguous.

## Sending messages

Send follow-up tasks to a running or idle agent:

```bash
jcode send <id> "now run the tests"
jcode send <id> --image screenshot.png "what's wrong here?"
jcode send <id> --no-wait "queue this task"
```

## Viewing logs

```bash
jcode logs <id>                  # Full timeline
jcode logs <id> -f               # Follow (streaming)
jcode logs <id> --tail 10        # Last 10 entries
jcode logs <id> --filter tools   # Only tool calls
```

## Waiting for agents

Block until an agent finishes its current task:

```bash
jcode wait <id>
jcode wait <id> --timeout 60   # 60 second timeout
```

Useful in scripts or when one agent needs to wait for another.

## Schedules

Run an agent on a cron schedule. The CLI also accepts simple cadence presets and compiles them to cron. See [Schedules from the CLI](/docs/schedules-cli) for the full reference.

```bash
jcode schedule create --every 30m --cwd ~/dev/my-app "Continue the refactor and leave a note."
jcode schedule ls
jcode schedule pause <id>
```

## Permissions

Agents may request permission for certain actions. Manage these from the CLI:

```bash
jcode permit ls                # List pending requests
jcode permit allow <id>        # Allow all pending for agent
jcode permit deny <id> --all   # Deny all pending
```

## Agent modes

Change an agent's operational mode (provider-specific):

```bash
jcode agent mode <id> --list   # Show available modes
jcode agent mode <id> bypass   # Set bypass mode
jcode agent mode <id> plan     # Set plan mode
jcode agent detach <id>        # Make a subagent top-level
```

Detaching is an explicit lifecycle action, not a creation flag. The agent keeps running; only its relationship to its parent changes.

## Daemon management

```bash
jcode daemon start             # Start the daemon
jcode daemon start --web-ui    # Start and serve the bundled web UI
jcode daemon status            # Check status
jcode daemon stop              # Stop the daemon
```

Use `JCODE_HOME` to run multiple isolated daemon instances.

## Connecting to a remote daemon

`--host` accepts either a local target (`host:port`, a unix socket, or a Windows pipe) or a pairing offer URL, the same `https://app.vpnla.pro/#offer=...` link the mobile app uses for QR pairing. With an offer URL the CLI connects through the JCode relay with end-to-end encryption, so you can drive a daemon on another machine without exposing it to the network.

Get an offer URL from the daemon you want to control:

```bash
jcode daemon pair --json   # prints { url, qr, ... }
```

Use it from anywhere:

```bash
jcode ls --host 'https://app.vpnla.pro/#offer=eyJ2IjoyLC...'
jcode run --host "$OFFER_URL" "fix the failing tests"
```

You can also set it once via `JCODE_HOST` instead of passing `--host` on every command.

## Multi-agent workflows

The CLI is designed to be used by agents themselves. You can instruct an agent to spawn sub-agents for parallel work:

```bash
# Agent A spawns Agent B and waits for it
agent_id=$(jcode run --background --quiet --title api-agent "implement the API")
jcode wait "$agent_id"
jcode logs "$agent_id" --tail 5
```

Because Agent A's ID is present in the environment, Agent B is created as its subagent in the same workspace unless `--workspace` is specified.

Simple implement + verify loop:

```bash
# Requires jq
while true; do
  jcode run --provider codex "make the tests pass" >/dev/null

  verdict=$(jcode run --provider claude --output-schema '{"type":"object","properties":{"criteria_met":{"type":"boolean"}},"required":["criteria_met"],"additionalProperties":false}' "ensure tests all pass")
  if echo "$verdict" | jq -e '.criteria_met == true' >/dev/null; then
    echo "criteria met"
    break
  fi
done
```

This pattern enables hierarchical task decomposition, a lead agent can break down work, delegate to specialists, and synthesize results.

## Output formats

Most commands support multiple output formats for scripting:

```bash
jcode ls --json                # JSON output
jcode ls --format yaml         # YAML output
jcode ls -q                    # IDs only (quiet)
```

## Global options

- `--host <target>`, connect to a different daemon (`host:port`, unix socket, or `https://app.vpnla.pro/#offer=...` for relay). See [Connecting to a remote daemon](#connecting-to-a-remote-daemon).
- `--json`, JSON output
- `-q, --quiet`, minimal output
- `--no-color`, disable colors