dec47d72d9
* docs: rename to lowercase + drop leftover plans Rename docs in docs/ to lowercase kebab-case for consistency and update all references in CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, packages/server/CLAUDE.md, and inter-doc links. Drop two leftover design plan docs: - docs/ATTACHMENT_BASED_REVIEW_CONTEXT_PLAN.md - docs/plan-approval-normalization.md * docs: drop stale uppercase entries from case-insensitive rename * feat(website): power /docs from public-docs/ markdown tree Move website docs out of TSX route components and into a root-level public-docs/ directory of plain markdown files with frontmatter (title, description, nav, order). - Add packages/website/src/docs.ts loader using import.meta.glob with ?raw to compile the markdown into the bundle at build time. - Replace the 9 hand-written docs/*.tsx routes with a single $.tsx catch-all that renders any slug via react-markdown. - Drive the docs sidebar nav from frontmatter order/nav. - Auto-discover docs routes in vite.config.ts so the sitemap stays in sync without manual edits. * fix(website): bind dev server to 0.0.0.0 so port collisions trigger fallback `host: "127.0.0.1"` (or unset) lets macOS coexist with another process holding an IPv6 dual-stack `*:8082` socket, so Vite never sees EADDRINUSE and silently binds alongside it. Forcing IPv4 wildcard makes the conflict real, and Vite's default `strictPort: false` falls through to the next free port. * fix(website): restore docs page styling after markdown migration Add a .docs-prose class that mirrors the styling the original docs/*.tsx components hand-rolled (h1/h2/h3 sizes, paragraph/list spacing, link colors, code blocks, callout-style blockquotes). ReactMarkdown was emitting unstyled HTML because the previous wrapper class only had inline-code rules — headings and code blocks fell back to user-agent defaults.
4.9 KiB
title, description, nav, order
| title | description | nav | order |
|---|---|---|---|
| CLI | Paseo CLI reference: manage agents, daemons, permissions, and worktrees from your terminal. | CLI | 5 |
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. This enables multi-agent workflows where one agent delegates subtasks to others and waits for results.
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 --detach "run the full test suite" # background
paseo run --worktree feature-x "implement feature X"
paseo run --output-schema schema.json "extract release notes"
paseo run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "summarize release notes"
The --worktree flag creates the agent in an isolated git worktree, useful for parallel feature development.
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 --detach.
By default, paseo run waits for completion. Use --detach to run in the background.
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.
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
Daemon management
paseo daemon start # Start the daemon
paseo daemon status # Check status
paseo daemon stop # Stop the daemon
Use PASEO_HOME to run multiple isolated daemon instances.
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
paseo run --detach "implement the API" --name api-agent
paseo wait api-agent
paseo logs api-agent --tail 5
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 <host:port>— connect to a different daemon--json— JSON output-q, --quiet— minimal output--no-color— disable colors