paseo/public-docs/cli.md

title, description, nav, order, category

title	description	nav	order	category
CLI	Paseo CLI reference: manage projects, workspaces, agents, plugins, scripts, schedules, daemons, and permissions from your terminal.	CLI	3	Getting started

CLI

The Paseo 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 Paseo CLI to spawn and manage other agents. Paseo recognizes the calling agent, so CLI-created workers get the same workspace and parent defaults as MCP-created workers.

Quick reference

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

Provider diagnostics

Ask the daemon to inspect the provider environment it actually uses:

paseo provider diagnostic claude
paseo provider diagnostic codex --json
paseo provider diagnostic opencode --host devbox:6767

The diagnostic includes the configured command, daemon PATH and shell, matching binaries, resolved path, version, model count, and provider status. Use --host for a remote daemon. This is the same diagnostic shown under Settings → your host → Providers → provider → Diagnostic.

Running agents

Use paseo run to start a new agent with a task:

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

From a human shell, a bare paseo run creates a new local workspace for the current directory. Use --workspace <id> to add the agent to an existing workspace, or --new-workspace local|worktree to explicitly create a separate workspace for the run.

Worktree creation accepts --worktree-mode branch-off|checkout-branch|checkout-pr plus the matching --new-branch/--base, --branch, or --pr-number/--forge options. Use --worktree-slug to choose the managed directory slug.

When an existing Paseo agent runs the same command, Paseo recognizes it through PASEO_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, paseo run waits for completion. Use --background to return immediately while the agent keeps running.

Projects

Register the current directory as a project, then list the projects known to the daemon:

cd ~/dev/my-app
paseo project create
paseo project ls

Use the project ID from paseo project ls to rename, reset, or delete a project:

paseo project rename <project-id> "My app"
paseo project rename <project-id> --reset
paseo project delete <project-id>

--reset restores the name derived from the project directory. Deleting a project archives its active workspaces and removes the project from Paseo. It does not delete the project directory.

For a local daemon, paseo project create [path] defaults to the current directory and resolves relative paths on the CLI machine. When you use --host or PASEO_HOST, provide a path that the target daemon can access:

paseo project create /srv/repos/api --host devbox:6767

The remote daemon interprets that path on its own machine. See Workspaces for how projects group working directories and sessions.

Workspaces

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

paseo workspace create --isolation local --path ~/dev/my-app --title main

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

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

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

Then list, use, rename, or archive it:

paseo workspace ls
paseo run --workspace <workspace-id> "implement authentication"
paseo workspace rename <workspace-id> "Auth rework"
paseo workspace rename <workspace-id> --reset   # back to the branch or directory name
paseo workspace archive <workspace-id>

Add --forge <name> to PR checkout when Paseo cannot infer the forge from the source checkout. See Git worktrees for setup hooks and services.

Workspace scripts

List, start, and stop the scripts configured in a workspace's paseo.json:

paseo script ls
paseo script start web
paseo script stop web

By default, Paseo selects the workspace whose directory is the current directory. Pass --cwd <path> to select a different directory, or --workspace <workspace-id> when a directory has multiple workspaces. These commands also accept --host and the standard output options such as --json.

The output includes each script's lifecycle and supervised terminal ID. Services also include their assigned port, proxy URL, and health. See Git worktrees for paseo.json configuration.

Plugins

Create and manage trusted local plugins on a daemon:

paseo plugin init /absolute/path/to/plugin
paseo plugin install /absolute/path/to/plugin
paseo plugin ls
paseo plugin reload my-plugin
paseo plugin logs my-plugin
paseo plugin disable my-plugin
paseo plugin enable my-plugin
paseo plugin remove my-plugin

paseo plugin logs <id> returns the plugin's recent daemon-side stdout and stderr. Add --json for structured entries or --host <target> for another daemon. See the Plugin reference for installation, trust, lifecycle, and log-retention behavior.

Listing agents

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

Streaming output

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

paseo 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:

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

Viewing logs

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

Waiting for agents

Block until an agent finishes its current task:

paseo wait <id>
paseo 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 for the full reference.

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

Permissions

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

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

Agent modes

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

paseo agent mode <id> --list   # Show available modes
paseo agent mode <id> bypass   # Set bypass mode
paseo agent mode <id> plan     # Set plan mode
paseo 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

paseo daemon start             # Start the daemon
paseo daemon start --web-ui    # Start and serve the bundled web UI
paseo daemon status            # Check status
paseo reload                    # Reload config.json (top-level alias)
paseo daemon reload             # Reload config.json
paseo daemon stop              # Stop the daemon

Reload validates the whole file, applies runtime-safe changes, and reports appliedPaths, restartRequiredPaths, and overrideControlledPaths. Human output prints paseo daemon restart only when a changed setting needs it. Use --json or --format yaml for the structured result, and --host to reload a remote daemon's own configuration file. An older host that does not support reload returns an update-host error.

Use PASEO_HOME to run multiple isolated daemon instances.

Hub

paseo hub login [url]          # Approve and store organization-scoped CLI access
paseo hub init                 # Guided setup: scaffold and deploy a starter bundle here
paseo hub connect [url]        # Enroll this daemon using CLI access
paseo hub projects             # List projects in the authenticated organization
paseo hub status               # Show the current Hub relationship
paseo hub disconnect           # End it
paseo hub deploy -p <project>  # Discover, validate, and activate a Hub bundle
paseo hub deploy -p <project> --dry-run # Validate without activating
paseo hub logout               # Remove the active stored CLI login

Run deploy from the project root. It reads .paseo/hub.yml, every direct .paseo/workflows/*.yml file, and referenced .paseo/workflows/partials/* files in deterministic path order. It does not search parents, accept an alternate resource path, or flatten the bundle into monolithic YAML.

Pass -p, --project <slug> to select the target project. --dry-run performs the same discovery and server validation without recording or activating a revision. Both outputs include the resolved Hub, project, and discovered workflow count.

login opens the Hub approval page and stores a durable organization-scoped CLI credential under PASEO_HOME. In an interactive terminal it then asks whether to connect this daemon and whether to initialize and deploy a starter workflow, both defaulting to yes. Declining the connection prints paseo hub connect <origin>; then paseo hub init, because the connection alone does not produce a bundle; declining only the starter prints paseo hub init. --json and non-TTY login remain login-only and never prompt. The stored login is separate from the daemon relationship created by connect.

init runs the same guided setup on its own and requires a TTY. It connects the daemon, uses the organization's only project or asks which one, and lists the Hub app connections that can back a starter workflow. One usable connection is selected automatically; with several, you choose a Trigger connection. If none is ready, setup sends you to Hub → Apps and stops before selecting an agent or writing files.

Setup then asks which agent provider, model, and mode the starter should run, choosing from what the connected daemon reports. A provider is offered only when the daemon has it enabled with a selectable model. Suggested model and mode entries are the daemon's defaults; no provider is suggested merely because it appears first. The mode question is skipped for providers that expose no modes and asked explicitly when the daemon has modes but no default. Finally, setup asks for the identity that gates the chosen connection: a GitHub username, a Slack member ID, or a Discord user ID. It writes .paseo/hub.yml and .paseo/workflows/<provider>-help.yml, validates them against Hub, and deploys. An existing .paseo/ directory is replaced only after you confirm. See the generated starter bundle.

Interactive logout checks the same-origin daemon relationship and asks whether to disconnect before deleting the login. Declining removes only the login. JSON and noninteractive logout never prompt or disconnect implicitly; --disconnect-daemon is the explicit automation path, and --force applies to that daemon disconnection. If a requested disconnection fails, the login is preserved.

Every command resolves and normalizes its destination before Hub or daemon work. Origin precedence is an explicit command origin or --hub, then PASEO_HUB_URL, then the active stored login origin, then the hosted default https://hub.paseo.sh. The hosted default never overrides an active login. Credential precedence is --api-key <secret>, then PASEO_HUB_API_KEY, then a stored login for the exact resolved origin. A stored credential is never sent to a different origin. API keys passed through flags or the environment are not stored.

Human output reports the resolved destination before each action. JSON output keeps stdout machine-readable and includes the normalized Hub origin. Bundle diagnostics identify paths without printing configuration contents or credentials.

See Daemons in Hub, Hub configuration, and the Hub public API.

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.paseo.sh/#offer=... link the mobile app uses for QR pairing. With an offer URL the CLI connects through the Paseo 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:

paseo daemon pair          # asks before enabling relay, then prints the QR and link
paseo daemon pair --relay  # enables relay without prompting
paseo daemon pair --json   # structured output; never prompts

Relay is off for new installations. In non-interactive or JSON mode, a disabled relay returns a RELAY_DISABLED error; pass --relay to provide explicit consent. Relay pairing is end-to-end encrypted. See Security.

Use it from anywhere:

paseo ls --host 'https://app.paseo.sh/#offer=eyJ2IjoyLC...'
paseo run --host "$OFFER_URL" "fix the failing tests"

You can also set it once via PASEO_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:

# Agent A spawns Agent B and waits for it
agent_id=$(paseo run --background --quiet --title api-agent "implement the API")
paseo wait "$agent_id"
paseo 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:

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

  verdict=$(paseo 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:

paseo ls --json                # JSON output
paseo ls --format yaml         # YAML output
paseo ls -q                    # IDs only (quiet)

Global options

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