Mohamed BoudraandGitHub
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.
167 lines
4.9 KiB
Markdown
167 lines
4.9 KiB
Markdown
---
|
|
title: CLI
|
|
description: "Paseo CLI reference: manage agents, daemons, permissions, and worktrees from your terminal."
|
|
nav: CLI
|
|
order: 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```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 <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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```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 <host:port>` — connect to a different daemon
|
|
- `--json` — JSON output
|
|
- `-q, --quiet` — minimal output
|
|
- `--no-color` — disable colors
|