From 59efb21d6eae5b07c3509e923e585a57a5aac4a2 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Thu, 5 Feb 2026 15:12:16 +0700 Subject: [PATCH] docs(website): add CLI documentation page --- packages/website/src/routeTree.gen.ts | 21 +++ packages/website/src/routes/docs.tsx | 1 + packages/website/src/routes/docs/cli.tsx | 230 +++++++++++++++++++++++ 3 files changed, 252 insertions(+) create mode 100644 packages/website/src/routes/docs/cli.tsx diff --git a/packages/website/src/routeTree.gen.ts b/packages/website/src/routeTree.gen.ts index f50bf16e1..91e83a05f 100644 --- a/packages/website/src/routeTree.gen.ts +++ b/packages/website/src/routeTree.gen.ts @@ -14,6 +14,7 @@ import { Route as IndexRouteImport } from './routes/index' import { Route as DocsIndexRouteImport } from './routes/docs/index' import { Route as DocsSecurityRouteImport } from './routes/docs/security' import { Route as DocsConfigurationRouteImport } from './routes/docs/configuration' +import { Route as DocsCliRouteImport } from './routes/docs/cli' import { Route as DocsBestPracticesRouteImport } from './routes/docs/best-practices' const DocsRoute = DocsRouteImport.update({ @@ -41,6 +42,11 @@ const DocsConfigurationRoute = DocsConfigurationRouteImport.update({ path: '/configuration', getParentRoute: () => DocsRoute, } as any) +const DocsCliRoute = DocsCliRouteImport.update({ + id: '/cli', + path: '/cli', + getParentRoute: () => DocsRoute, +} as any) const DocsBestPracticesRoute = DocsBestPracticesRouteImport.update({ id: '/best-practices', path: '/best-practices', @@ -51,6 +57,7 @@ export interface FileRoutesByFullPath { '/': typeof IndexRoute '/docs': typeof DocsRouteWithChildren '/docs/best-practices': typeof DocsBestPracticesRoute + '/docs/cli': typeof DocsCliRoute '/docs/configuration': typeof DocsConfigurationRoute '/docs/security': typeof DocsSecurityRoute '/docs/': typeof DocsIndexRoute @@ -58,6 +65,7 @@ export interface FileRoutesByFullPath { export interface FileRoutesByTo { '/': typeof IndexRoute '/docs/best-practices': typeof DocsBestPracticesRoute + '/docs/cli': typeof DocsCliRoute '/docs/configuration': typeof DocsConfigurationRoute '/docs/security': typeof DocsSecurityRoute '/docs': typeof DocsIndexRoute @@ -67,6 +75,7 @@ export interface FileRoutesById { '/': typeof IndexRoute '/docs': typeof DocsRouteWithChildren '/docs/best-practices': typeof DocsBestPracticesRoute + '/docs/cli': typeof DocsCliRoute '/docs/configuration': typeof DocsConfigurationRoute '/docs/security': typeof DocsSecurityRoute '/docs/': typeof DocsIndexRoute @@ -77,6 +86,7 @@ export interface FileRouteTypes { | '/' | '/docs' | '/docs/best-practices' + | '/docs/cli' | '/docs/configuration' | '/docs/security' | '/docs/' @@ -84,6 +94,7 @@ export interface FileRouteTypes { to: | '/' | '/docs/best-practices' + | '/docs/cli' | '/docs/configuration' | '/docs/security' | '/docs' @@ -92,6 +103,7 @@ export interface FileRouteTypes { | '/' | '/docs' | '/docs/best-practices' + | '/docs/cli' | '/docs/configuration' | '/docs/security' | '/docs/' @@ -139,6 +151,13 @@ declare module '@tanstack/react-router' { preLoaderRoute: typeof DocsConfigurationRouteImport parentRoute: typeof DocsRoute } + '/docs/cli': { + id: '/docs/cli' + path: '/cli' + fullPath: '/docs/cli' + preLoaderRoute: typeof DocsCliRouteImport + parentRoute: typeof DocsRoute + } '/docs/best-practices': { id: '/docs/best-practices' path: '/best-practices' @@ -151,6 +170,7 @@ declare module '@tanstack/react-router' { interface DocsRouteChildren { DocsBestPracticesRoute: typeof DocsBestPracticesRoute + DocsCliRoute: typeof DocsCliRoute DocsConfigurationRoute: typeof DocsConfigurationRoute DocsSecurityRoute: typeof DocsSecurityRoute DocsIndexRoute: typeof DocsIndexRoute @@ -158,6 +178,7 @@ interface DocsRouteChildren { const DocsRouteChildren: DocsRouteChildren = { DocsBestPracticesRoute: DocsBestPracticesRoute, + DocsCliRoute: DocsCliRoute, DocsConfigurationRoute: DocsConfigurationRoute, DocsSecurityRoute: DocsSecurityRoute, DocsIndexRoute: DocsIndexRoute, diff --git a/packages/website/src/routes/docs.tsx b/packages/website/src/routes/docs.tsx index 42d46928b..28c68130b 100644 --- a/packages/website/src/routes/docs.tsx +++ b/packages/website/src/routes/docs.tsx @@ -7,6 +7,7 @@ export const Route = createFileRoute('/docs')({ const navigation = [ { name: 'Getting started', href: '/docs' }, + { name: 'CLI', href: '/docs/cli' }, { name: 'Configuration', href: '/docs/configuration' }, { name: 'Security', href: '/docs/security' }, { name: 'Best practices', href: '/docs/best-practices' }, diff --git a/packages/website/src/routes/docs/cli.tsx b/packages/website/src/routes/docs/cli.tsx new file mode 100644 index 000000000..0a561e5c1 --- /dev/null +++ b/packages/website/src/routes/docs/cli.tsx @@ -0,0 +1,230 @@ +import { createFileRoute } from '@tanstack/react-router' + +export const Route = createFileRoute('/docs/cli')({ + head: () => ({ + meta: [ + { title: 'CLI - Paseo Docs' }, + { + name: 'description', + content: 'Paseo CLI reference: manage agents, daemons, permissions, and worktrees from your terminal.', + }, + ], + }), + component: CLI, +}) + +function Code({ children }: { children: React.ReactNode }) { + return ( +
+ {children} +
+ ) +} + +function CLI() { + return ( +
+
+

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 callout */} +
+
+ 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 */} +
+

Quick reference

+ + 
{`paseo run "fix the tests"           # Start an agent
+paseo ls                             # List running agents
+paseo attach                     # Stream agent output
+paseo send  "also fix linting"  # Send follow-up task
+paseo logs                       # View agent timeline
+paseo stop                       # Stop an agent`}
+ +
+ + {/* Running agents */} +
+

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"`}
+ +

+ The --worktree flag creates the agent in an isolated git + worktree, useful for parallel feature development. +

+
+ + {/* Listing agents */} +
+

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 */} +
+

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 */} +
+

Sending messages

+

+ Send follow-up tasks to a running or idle agent: +

+ + 
{`paseo send  "now run the tests"
+paseo send  --image screenshot.png "what's wrong here?"
+paseo send  --no-wait "queue this task"`}
+ +
+ + {/* Viewing logs */} +
+

Viewing logs

+ + 
{`paseo logs                   # Full timeline
+paseo logs  -f               # Follow (streaming)
+paseo logs  --tail 10        # Last 10 entries
+paseo logs  --filter tools   # Only tool calls`}
+ +
+ + {/* Waiting for agents */} +
+

Waiting for agents

+

+ Block until an agent finishes its current task: +

+ + 
{`paseo wait 
+paseo wait  --timeout 60   # 60 second timeout`}
+ +

+ Useful in scripts or when one agent needs to wait for another. +

+
+ + {/* Permissions */} +
+

Permissions

+

+ Agents may request permission for certain actions. Manage these from the CLI: +

+ + 
{`paseo permit ls                # List pending requests
+paseo permit allow         # Allow all pending for agent
+paseo permit deny  --all   # Deny all pending`}
+ +
+ + {/* Agent modes */} +
+

Agent modes

+

+ Change an agent's operational mode (provider-specific): +

+ + 
{`paseo agent mode  --list   # Show available modes
+paseo agent mode  bypass   # Set bypass mode
+paseo agent mode  plan     # Set plan mode`}
+ +
+ + {/* Daemon management */} +
+

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 */} +
+

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`}
+ +

+ This pattern enables hierarchical task decomposition — a lead agent can break down work, + delegate to specialists, and synthesize results. +

+
+ + {/* Output formats */} +
+

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 */} +
+

Global options

+
    +
  • + --host <host:port> — connect to a different daemon +
    • +
  • + --json — JSON output +
    • +
  • + -q, --quiet — minimal output +
    • +
  • + --no-color — disable colors +
    • +
+
+
+ ) +}