Mohamed BoudraandGitHub
dfd18a44a7
* feat(website): nest docs pages under landable groups The docs sidebar could already render groups from subdirectories in public-docs, but nothing used it because every doc was a flat file, and two things stopped it being usable. A group had no page of its own, so its label was only a toggle and its name came from the directory name via formatLabel. A directory's index.md now supplies the group's label, order, and href, which makes the group landable and lets the label be authored rather than derived. Categories and top-level directories named the same thing, so a categorised doc at hub/index.md produced a group nested inside its own category. Only directories below the top level become groups now. Also fixes two behaviours in the sidebar: - The open/closed effect assigned containsActive on every change, so a group you expanded to browse collapsed the moment you navigated anywhere else. Navigating in now opens a group and navigating away leaves it alone. - The sidebar scrolls independently of the page and never scrolled the active entry into view, so loading or refreshing a page far down the list left the sidebar parked at the top with no visible position. The group row is a single target: it navigates and expands, and collapses when clicked again from the page it points at. A separate chevron button would put two actions a few pixels apart. * docs(hub): document Hub Adds a Hub section covering what it is, how it works, daemons, triggers, configuration, activity, and the two ways to run it. The section separates using Hub from running it. Overview, quickstart, daemons, triggers, and configuration hold regardless of who operates the deployment; the self-hosting branch owns deploying the service and creating the GitHub, Slack, and Discord apps it talks to. That split falls on a real seam, because those apps are exactly what a hosted Hub would own on your behalf. Hosted is a placeholder until it ships. Each provider gets a trigger page carrying its events, filter semantics, and the full paseo.event.* reference for the data a prompt can read. That data is the thing a config author actually needs and the thing they cannot get from anywhere else. Every YAML block was parsed against the Hub config schema rather than eyeballed, which kept several plausible-looking things out of the docs: worktree prNumber takes a literal number and not a merge variable, only daemon environments run today, and github.push has no actor so it can never satisfy the required from_users filter. Troubleshooting moves to order 90 so it stays last. * refactor(website): let the active docs entry scroll itself into view The layout queried the sidebar for the active entry after every navigation, which coupled it to when that entry mounts. A link inside a collapsed group only mounts once the group's own effect opens it, so the query could run against a DOM that does not contain it yet. Moving the scroll to the entry removes the ordering question rather than answering it, and drops the ref and the cross-component query. Reported by Greptile on #2864. The failure it described does not reproduce: navigating from a page outside a collapsed group into one of its children still scrolls correctly, verified with the group confirmed collapsed and the sidebar forced to the top. The coupling was real even though the bug was not. * docs(hub): stop listing BETTER_AUTH_URL as required It falls back to PASEO_CLOUD_PUBLIC_URL, so a deployment that sets the public origin already has a correct auth base URL. Listing it as required made the Fly recipe look incomplete when it was not. Moved to optional with its default, and recorded what actually breaks without BETTER_AUTH_SECRET: the auth routes close and nobody can sign in. Reported by Codex on #2864, which read the same inconsistency the other way round and proposed adding the variable to the Fly example. * docs(hub): attach a database in the Fly recipe The Fly section showed inline config and a secrets command, neither of which supplied DATABASE_URL. It defaults to localhost:5432, which on Fly reaches nothing, so the documented deployment could not start. fly postgres attach sets DATABASE_URL as a secret, so the step is the attach itself rather than another variable to copy. Reported by Codex on #2864. * docs: align Hub self-hosting contract
9.6 KiB
title, description, nav, order, category
| title | description | nav | order | category |
|---|---|---|---|---|
| CLI | Paseo CLI reference: manage agents, workspaces, 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
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 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.
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 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, or archive it:
paseo workspace ls
paseo run --workspace <workspace-id> "implement authentication"
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.
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 daemon stop # Stop the daemon
Use PASEO_HOME to run multiple isolated daemon instances.
Hub
paseo hub connect <url> # Enroll this daemon with a Paseo Hub
paseo hub status # Show the current Hub relationship
paseo hub disconnect # End it
See Daemons in Hub.
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, orhttps://app.paseo.sh/#offer=...for relay). See Connecting to a remote daemon.--json, JSON output-q, --quiet, minimal output--no-color, disable colors