--- title: CLI description: "Paseo CLI reference: manage projects, workspaces, agents, plugins, scripts, schedules, daemons, and permissions from your terminal." nav: CLI order: 3 category: 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 ```bash paseo run "fix the tests" # Start an agent paseo ls # List running agents paseo attach # Stream agent output paseo send "also fix linting" # Send follow-up task paseo logs # View agent timeline paseo stop # Stop an agent ``` ## Provider diagnostics Ask the daemon to inspect the provider environment it actually uses: ```bash 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: ```bash 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 "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 ` 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: ```bash 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: ```bash paseo project rename "My app" paseo project rename --reset paseo project delete ``` `--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: ```bash paseo project create /srv/repos/api --host devbox:6767 ``` The remote daemon interprets that path on its own machine. See [Workspaces](/docs/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: ```bash 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: ```bash paseo workspace ls paseo run --workspace "implement authentication" paseo workspace rename "Auth rework" paseo workspace rename --reset # back to the branch or directory name paseo workspace archive ``` Add `--forge ` to PR checkout when Paseo cannot infer the forge from the source checkout. See [Git worktrees](/docs/worktrees) for setup hooks and services. ## Workspace scripts List, start, and stop the scripts configured in a workspace's `paseo.json`: ```bash 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 ` to select a different directory, or `--workspace ` 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](/docs/worktrees#scripts-and-services) for `paseo.json` configuration. ## Plugins Create and manage trusted local plugins on a daemon: ```bash 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 ` returns the plugin's recent daemon-side stdout and stderr. Add `--json` for structured entries or `--host ` for another daemon. See the [Plugin reference](/docs/plugins/reference) for installation, trust, lifecycle, and log-retention behavior. ## Listing agents ```bash 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: ```bash 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: ```bash paseo send "now run the tests" paseo send --image screenshot.png "what's wrong here?" paseo send --no-wait "queue this task" ``` ## Viewing logs ```bash paseo logs # Full timeline paseo logs -f # Follow (streaming) paseo logs --tail 10 # Last 10 entries paseo logs --filter tools # Only tool calls ``` ## Waiting for agents Block until an agent finishes its current task: ```bash paseo wait paseo wait --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 paseo schedule create --every 30m --cwd ~/dev/my-app "Continue the refactor and leave a note." paseo schedule ls paseo schedule pause ``` ## Permissions Agents may request permission for certain actions. Manage these from the CLI: ```bash paseo permit ls # List pending requests paseo permit allow # Allow all pending for agent paseo permit deny --all # Deny all pending ``` ## Agent modes Change an agent's operational mode (provider-specific): ```bash paseo agent mode --list # Show available modes paseo agent mode bypass # Set bypass mode paseo agent mode plan # Set plan mode paseo agent detach # 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 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 ```bash paseo hub login [url] # Approve and store organization-scoped CLI access 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 # Discover, validate, and activate a Hub bundle paseo hub deploy -p --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 ` 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`. The stored login is separate from the daemon relationship created by `connect`. 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 `, 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](/docs/hub/daemons), [Hub configuration](/docs/hub/configuration), and the [Hub public API](/docs/hub/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: ```bash 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](/docs/security). Use it from anywhere: ```bash 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: ```bash # 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: ```bash # 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: ```bash paseo ls --json # JSON output paseo ls --format yaml # YAML output paseo ls -q # IDs only (quiet) ``` ## Global options - `--host `, connect to a different daemon (`host:port`, unix socket, or `https://app.paseo.sh/#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