Getting started

Introduction

Paseo runs coding agents on your machines from a terminal, desktop, mobile, or web client.

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.

See: Create a worktree-backed workspace

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.

See: Multi-agent workflows

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.

See: Multi-agent workflows

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.

See: Connecting to a remote 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.

See: Create and Cadence

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.

See: Connecting to a remote daemon

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!