Getting started
Introduction
Paseo runs coding agents on your machines from a terminal, desktop, mobile, or web client.
- Paseo CLI reference (paseo.sh)
- Schedules from the CLI (paseo.sh)
- Getting started (paseo.sh)
- Paseo repository (github.com)
Install
npm install -g @getpaseo/cli
paseo # starts daemon, then offers pairing
The desktop app bundles a daemon; Paseo does not ship a coding agent, so install at least one provider CLI.
See: Server / CLI
First run
paseo run "fix the tests"
paseo ls
paseo attach <id> # stream output; Ctrl+C to detach
The CLI creates a local workspace for the current directory.
See: Quick reference
Agents
Run
paseo run "fix the tests"
paseo run --provider codex --no-wait "run the focused test suite"
paseo run --output-schema schema.json "name this branch"
paseo run --new-workspace worktree --worktree-mode branch-off \
--new-branch feature/x --base origin/main "implement feature X"
A bare run in an interactive shell creates a local workspace; --no-wait returns while the agent keeps running. --output-schema cannot combine with --no-wait.
See: Running agents
List
paseo ls
paseo ls -a
paseo ls -a -g --json
paseo ls -q
-a adds archived and background agents; -g crosses directories.
See: Listing agents
Attach and logs
paseo attach <id>
paseo logs <id> -f
paseo logs <id> --tail 10
paseo logs <id> --filter tools
IDs accept unambiguous prefixes.
See: Streaming output and Viewing logs
Send
paseo send <id> "now run the tests"
paseo send <id> --image screenshot.png "what's wrong here?"
paseo send <id> --behavior steer "continue on this path"
paseo send <id> --no-wait "run this task"
Agent-originated sends steer the running turn by default; other sends interrupt.
See: Sending messages
Wait and stop
paseo wait <id>
paseo wait <id> --timeout 60
paseo stop <id>
paseo stop --all
wait blocks until the current task finishes; stop is a no-op for idle agents.
See: Waiting for agents
Permissions and modes
paseo permit ls
paseo permit allow <id>
paseo permit deny <id> --all
paseo agent mode <id> --list
paseo agent mode <id> plan
Permission requests are per-agent; modes are provider-specific.
See: Permissions and Agent modes
Workspaces
Projects
cd ~/dev/my-app
paseo project create
paseo project ls
paseo project rename <project-id> "My app"
paseo project delete <project-id>
create [path] defaults to the current directory; with --host, the path is resolved on the daemon machine.
See: Projects
Create
paseo workspace create --isolation local \
--path ~/dev/my-app --title main
paseo workspace create --isolation worktree \
--path ~/dev/my-app --mode checkout-pr --pr-number 2186
paseo workspace create --isolation local --background \
--path /path/to/repo
--background hides a workspace from default discovery; --no-background overrides caller inheritance.
See: Workspaces
Worktrees
paseo run --new-workspace worktree \
--worktree-mode branch-off --new-branch feature/auth \
--base origin/main "implement auth"
paseo workspace create --isolation worktree \
--mode checkout-branch --branch feature/existing \
--worktree-slug existing-copy
Worktree modes are branch-off, checkout-branch, and checkout-pr; paseo.json scripts attach to the worktree.
Manage
paseo workspace ls
paseo workspace ls --background
paseo workspace rename <workspace-id> "Auth rework"
paseo workspace archive <workspace-id>
paseo workspace setup <id>
Inside an agent, PASEO_WORKSPACE_ID holds its own workspace ID.
See: Workspaces
Terminals and scripts
Terminals
paseo terminal create --workspace <workspace-id> --name Development
paseo terminal send-keys <terminal-id> -l "echo ready"
paseo terminal send-keys <terminal-id> Enter
paseo terminal capture <terminal-id>
paseo terminal ls --workspace <workspace-id> --json
paseo terminal kill <terminal-id>
Creation uses the workspace directory unless --cwd is given; ls --all lists every terminal on the host.
See: Terminals
Scripts
paseo script ls
paseo script start web
paseo script stop web
Scripts come from the workspace's paseo.json; services add port, proxy URL, and health.
See: Workspace scripts and Scripts and services
Orchestration
Subagents
agent_id=$(paseo run --no-wait --quiet \
--title api-agent "implement the API")
paseo wait "$agent_id"
paseo agent detach <id>
PASEO_AGENT_ID makes a new run a subagent in the same workspace unless --workspace is set. Detach changes only the parent relationship and the agent keeps running.
Verify loop
paseo run --provider codex "make the tests pass"
verdict=$(paseo run --provider claude --output-schema schema.json \
"ensure tests all pass")
echo "$verdict" | jq -e '.criteria_met == true'
A builder plus a verifier can loop until the verdict passes; jq reads the JSON schema output.
Remote hosts
paseo --host localhost:6767 host add \
'ssh://deploy@build-box' --label build-box --meta team=infra
paseo --host localhost:6767 host ls --json
paseo --host "$OFFER_URL" run "fix the failing tests"
--host also accepts pairing offers; relay connections are end-to-end encrypted and SSH hosts must already run a daemon.
Schedules
Create
paseo schedule create --every 30m --cwd ~/dev/my-app \
--name overnight-refactor --provider codex/gpt-5.5 \
"Continue the refactor. Run the focused checks."
paseo schedule create --cron "0 9 * * 1-5" \
--timezone America/New_York --name morning-triage \
"Review overnight CI failures."
--every compiles to cron, not a rolling interval; schedules default to UTC and --run-now fires once at creation.
Manage
paseo schedule ls
paseo schedule inspect <id>
paseo schedule logs <id>
paseo schedule pause <id>
paseo schedule resume <id>
paseo schedule run-once <id>
paseo schedule update <id> --every 10m --max-runs 6
paseo schedule delete <id>
Each run starts a fresh agent; run workspaces are archived when a run ends.
See: Manage
Heartbeats
paseo heartbeat create --cron "*/20 * * * *" \
--name heartbeat \
"Check the current task state and continue."
paseo heartbeat update <id> --cron "*/10 * * * *"
paseo heartbeat delete <id>
Heartbeats need PASEO_AGENT_ID and raw --cron. --every presets apply only to new-agent schedules.
See: Heartbeats
Daemon
Configure
paseo daemon config set daemon.listen 127.0.0.1:6799 \
--home ~/.paseo
paseo daemon config set daemon.relay.enabled false \
--home ~/.paseo
paseo daemon reload --home ~/.paseo
reload applies runtime-safe changes and never restarts implicitly.
See: Apply changes
Lifecycle
paseo daemon start --home ~/.paseo
paseo daemon status --home ~/.paseo
paseo daemon restart --home ~/.paseo
paseo daemon stop --home ~/.paseo
PASEO_LISTEN=127.0.0.1:6799 \
PASEO_RELAY_ENABLED=false \
paseo daemon run --home ~/.paseo
start backgrounds the daemon; stop --home waits for exit; run stays attached with launch-time env overrides.
See: Daemon management and Foreground deployments and migration
Pairing
paseo daemon pair --relay
paseo daemon pair --json
paseo --host "$OFFER_URL" ls
Relay is off by default; --relay opts in.
Reference
Global options
paseo --json ls
paseo ls --format yaml
paseo ls -q
paseo --no-color ls
Most commands accept these output flags; -q prints IDs only.
See: Global options
Select a daemon
paseo --home ~/.paseo ls
paseo --host devbox:6767 project ls
paseo --host "$OFFER_URL" run "fix the failing tests"
Selectors work before or after the command. Two selectors yield TARGET_AMBIGUOUS; there is no default-port fallback.
See: Select one daemon
Environment
PASEO_HOME=~/.paseo paseo ls
PASEO_HOST=devbox:6767 paseo ls
echo "$PASEO_AGENT_ID" # set inside agent sessions
echo "$PASEO_WORKSPACE_ID" # current agent's workspace
Flags override environment selectors; the agent variables are read-only inside sessions.
See: Select one daemon
Providers
paseo provider ls
paseo provider models claude
paseo provider diagnostic claude
paseo provider diagnostic codex --json
Provider diagnostics report the daemon's own PATH, binaries, and model count.
See: Provider diagnostics
Usage
paseo usage
paseo usage ls --refresh
paseo usage inspect <report-id>
paseo usage ls --json
Quota reports come from the host and --refresh bypasses the five-minute cache.
See: Account usage
Hub
paseo hub status
paseo hub login [url]
paseo hub permissions list
paseo hub deploy --dry-run
Grant hub.execute only to trusted automations.
See: Hub
Plugins
paseo plugin add owner/slug
paseo plugin ls
paseo plugin logs my-plugin
paseo plugin update --all
paseo plugin disable my-plugin
Plugins run unsandboxed with the daemon user's access: add only trusted sources.
See: Plugins
0 Comments for this cheatsheet. Write yours!