paseo/public-docs/cli.zh-CN.md

title, description, nav

title	description	nav
CLI 参考	Paseo CLI 参考：在终端中管理项目、工作区、Agent、插件、脚本、定时任务、daemon 和权限。	CLI 参考

CLI 参考

Paseo CLI 让你在终端中管理 Agent。它与 daemon 的 API 提供的接口相同，因此能在应用中做的事，都可以在命令行中完成。

Agent 编排：你可以让编程 Agent 使用 Paseo CLI 启动和管理其他 Agent。Paseo 会识别发起调用的 Agent，因此通过 CLI 创建的执行者与通过 MCP 创建的执行者获得相同的工作区和父级默认值。

速查

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
paseo usage                          # Show account quotas and balances

账号用量

显示主机用量来源中的账号配额和余额：

paseo usage
paseo usage ls --refresh
paseo usage ls --agent <agent-id>
paseo usage inspect <report-id>
paseo usage inspect <report-id> --refresh

paseo usage 等同于 paseo usage ls。摘要按账号对时间窗口和余额分组，并显示报告 ID、来源和账号标签、状态以及获取时间戳。缺失的值显示为 -；不可用和失败的报告会附带原因。

把列表中的完整报告 ID 复制到 inspect 中，可以查看重置时间、余额和单位、套餐详情、提供的预测，以及附带恢复说明的登录失败信息。报告 ID 需要完全匹配。

--agent 选择与某个 Agent 关联的账号配额。它不会统计该 Agent 的 token 消耗或费用。请使用完整的 Agent ID，并且不要把 --agent 与 inspect 一起使用。

查询会在可用时使用主机的五分钟缓存。添加 --refresh 可以绕过缓存。使用 --host 或 --home 选择一个 daemon。不支持用量来源的主机会返回一条更新提示。

在脚本中使用用量

paseo usage ls --json
paseo usage inspect <report-id> --json
paseo usage ls --quiet

列表的 JSON 始终是一个数组，没有返回报告时为 []。inspect 的 JSON 是一个报告条目。每个条目包含 id、sourceId、sourceLabel、account、fetchedAt 和一个嵌套的 report。访问其数据之前，请先读取 report.status：

状态	字段
available	windows，以及可选的 planLabel、balances 和 details
unavailable	problem，说明凭据过期、被拒绝或缺少配额
error	error，失败信息

条目还可能包含 loginErrors。结构化输出会保留数值和可选字段。支持标准的 --format yaml、--no-headers 和 --no-color 选项；--quiet 输出完整的报告 ID。

查询完成时以状态 0 退出，即使个别报告不可用或失败也是如此。连接或请求失败、不支持的主机、未知的报告 ID 以及相互冲突的选择器会以状态 1 退出，并把错误写到 stderr。结果为空时，人类可读的输出会显示 No usage reports returned；这并不能说明每个来源的账号发现是否都成功了。

已连接的主机

--host 选择要管理其已保存连接的 daemon。请用注册项的 registrationId，不要用标签。

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 localhost:6767 host inspect hst_123
paseo --host localhost:6767 host update hst_123 --meta team=tools --remove-meta obsolete
paseo --host localhost:6767 host update hst_123 --connection 'ssh://deploy@new-address'
paseo --host localhost:6767 host disable hst_123
paseo --host localhost:6767 host enable hst_123
paseo --host localhost:6767 host rm hst_123

add 接受 TCP/主机和端口、ws:///wss://、本地 socket/管道、SSH，以及 relay/配对 URL。 SSH 连接到已经运行的 daemon。如果该 daemon 需要密码，在 SSH URI 中添加 ?password=...（已有 daemonPort 时使用 &password=...）。无法访问的目标仍会保存，并自动重试。 ls 包括已禁用和连接失败的主机。inspect 包括不含凭据的连接详情和恢复说明。 JSON 输出不会包含连接凭据。

update --meta 替换指定的键；--remove-meta 删除键。替换连接会保留已固定的 daemon 身份。 只有确认目标已改变后，才应同时使用 --replace-identity 和 --connection。 rm 删除已保存的连接；该主机上的 Agent 和工作区会继续运行。

Provider 诊断

让 daemon 检查它实际使用的 Provider 环境：

paseo provider diagnostic claude
paseo provider diagnostic codex --json
paseo --host devbox:6767 provider diagnostic opencode

诊断信息包括配置的命令、daemon 的 PATH 和 shell、匹配到的二进制文件、解析出的路径、版本、模型数量和 Provider 状态。对于远程 daemon，请使用全局的 --host 选项。这与 设置 → 你的主机 → Providers → 对应 Provider → 诊断 下显示的诊断相同。

运行 Agent

使用 paseo run 启动一个带任务的新 Agent：

paseo run "implement user authentication"
paseo run --provider codex "refactor the API layer"
paseo run --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"
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"

在人工操作的 shell 中，不带参数的 paseo run 会为当前目录创建一个新的本地工作区。使用 --workspace <id> 把 Agent 加入一个已有的工作区，或者使用 --new-workspace local|worktree 为这次运行显式创建一个单独的工作区。

创建 worktree 时接受 --worktree-mode branch-off|checkout-branch|checkout-pr，以及相应的 --new-branch/--base、--branch 或 --pr-number/--forge 选项。使用 --worktree-slug 选择托管目录的 slug。

当一个已有的 Paseo Agent 运行同样的命令时，Paseo 会通过 PASEO_AGENT_ID 识别它。如果没有显式指定位置，新的 Agent 会成为它在同一工作区中的子 Agent。--workspace 可以把这个子 Agent 放到其他地方，而不改变它的父 Agent。

使用 --output-schema 只返回符合 schema 的 JSON 输出。你可以传入 schema 文件路径，或内联的 JSON schema 对象。此模式不能与 --no-wait 一起使用。

paseo run 默认等待完成。使用 --no-wait 可以立即返回，同时让 Agent 继续运行，paseo send 也使用同一个参数。

旧的 run --background 和 -d 别名仍然表示 --no-wait。它们已被弃用，不会出现在帮助中，并会向 stderr 输出警告。请在脚本中使用 --no-wait。工作区的可见性通过 workspace create --background 单独选择；本版本不会改变 run --background 的含义。

项目

把当前目录注册为项目，然后列出 daemon 知道的项目：

cd ~/dev/my-app
paseo project create
paseo project ls

使用 paseo project ls 中的项目 ID 重命名、重置或删除项目：

paseo project rename <project-id> "My app"
paseo project rename <project-id> --reset
paseo project delete <project-id>

--reset 恢复由项目目录推导出的名称。删除项目会归档它的活动工作区，并把项目从 Paseo 中移除。它不会删除项目目录。

对于本地 daemon，paseo project create [path] 默认使用当前目录，并在 CLI 所在机器上解析相对路径。当你使用全局的 --host 选项或 PASEO_HOST 时，请提供目标 daemon 能访问的路径：

paseo --host devbox:6767 project create /srv/repos/api

远程 daemon 会在它自己的机器上解释这个路径。项目如何对工作目录和会话分组，见工作区。

工作区

如果你想在启动 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 origin/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

添加 --background 可以把工作区从默认的发现结果中隐藏。它的 Agent 和终端保留普通的历史记录、持久化、钩子和重启恢复。--no-background 显式覆盖从调用方工作区继承的设置；省略时，由 Paseo Agent 运行则继承，在人工操作的 shell 中默认为 false。可见性只能在创建时设置。

paseo workspace create --isolation local --background --path /path/to/repo
paseo run --workspace <workspace-id> --no-wait "review the checkout flow"

无论在列表中是否可见，都可以通过确切的工作区 ID 和 Agent ID 访问它们。

然后列出、使用、重命名或归档它：

paseo workspace ls
paseo workspace ls --background               # Also include background workspaces
paseo run --workspace <workspace-id> "implement authentication"
paseo workspace rename <workspace-id> "Auth rework"
paseo workspace rename <workspace-id> --reset   # back to the branch or directory name
paseo workspace archive <workspace-id>

当 Paseo 无法从源检出推断代码托管平台时，为 PR 检出添加 --forge <name>。setup 钩子和服务见 Git worktree。

终端

当多个工作区共享同一个目录时，请使用工作区 ID：

paseo terminal create --workspace <workspace-id> --name Development
paseo terminal ls --workspace <workspace-id> --json
paseo terminal send-keys <terminal-id> -l "echo ready"
paseo terminal send-keys <terminal-id> Enter
paseo terminal capture <terminal-id>
paseo terminal kill <terminal-id>

创建时默认使用工作区目录。添加 --cwd <absolute-path> 可以修改进程目录，同时仍由该工作区拥有。未知或已归档的工作区 ID 会失败。

不带 --workspace 时，创建会打开 --cwd 或当前目录对应的项目，并复用其中最早的活动工作区。不带 --workspace 的列表会按 --cwd 或当前目录过滤，可能包含多个工作区。ls --all 列出主机上的所有终端，不能与目录或工作区过滤条件一起使用。

创建和列表的结果包含 id、name、cwd 和 workspaceId。使用 --json 获得结构化输出，使用全局的 --host 选项指定另一个 daemon。这些命令需要一个支持工作区终端 API 的主机；较旧的主机会返回一条更新提示。

工作区脚本

列出、启动和停止在工作区的 paseo.json 中配置的脚本：

paseo script ls
paseo script start web
paseo script stop web

Paseo 默认选择目录为当前目录的工作区。传入 --cwd <path> 选择另一个目录，当一个目录有多个工作区时传入 --workspace <workspace-id>。使用全局的 --host 选项指定另一个 daemon。这些命令也接受 --json 等标准输出选项。

输出包含每个脚本的生命周期和受监管的终端 ID。服务还包含它们分配到的端口、代理 URL 和健康状态。paseo.json 的配置见 Git worktree。

插件

信任你添加的每一个插件。paseo plugin add 和 paseo plugin install 的含义是“我信任这个代码库”。插件的服务端代码和 Git 准备命令在 daemon 主机上以 daemon 用户的权限运行，没有沙盒；客户端贡献在 Paseo 内部运行。依赖和将来的更新也是这个决定的一部分。使用全局的 --host 选项时，命令在远程 daemon 主机上运行。

在 daemon 上创建和管理受信任的插件：

paseo plugin init ./plugin
paseo plugin install ./plugin
paseo plugin add owner/slug
paseo plugin add git:owner/repository
paseo plugin add https://gitlab.com/group/repository.git --ref main
paseo plugin add git:owner/monorepo:plugins/review
paseo plugin ls [id]
paseo plugin update my-plugin
paseo plugin update --all
paseo plugin reload my-plugin
paseo plugin logs my-plugin
paseo plugin disable my-plugin
paseo plugin enable my-plugin
paseo plugin remove my-plugin

paseo plugin reload <id> 报告重新加载本身的结果：在 daemon 停止并启动插件期间，无论耗时多久，它都会等待，并且会排在 daemon 的其他插件工作之后。取消命令或丢失连接不会停止 daemon 的工作，也没有任何列表或日志条目能确定被取消的重新加载做了什么——这些中间状态见插件参考。再次运行重新加载才能得到结果：它会等待尚未完成的那一次，然后再停止并启动插件一次。

不带前缀的 owner/slug 会安装经过审查的注册表展示项。GitHub 源码使用 git:owner/repository，本地目录使用 ./plugin。对于 monorepo 中的插件，追加 :<directory>。

paseo plugin ls [id] 不会联系远程。paseo plugin logs <id> 返回插件最近的 daemon 端 stdout 和 stderr。添加 --json 获得结构化条目，或运行 paseo --host <target> plugin logs <id> 查看另一个 daemon。安装、信任、生命周期和日志保留行为见插件参考。

列出 Agent

paseo ls                    # Non-archived agents in active workspaces
paseo ls -a                 # Also include archived agents
paseo ls -g                 # Non-archived agents across all workspaces
paseo ls -a -g --json       # All agents, including archived, as JSON
paseo ls --background       # Also include agents in background workspaces

流式输出

使用 paseo attach 实时查看 Agent 的输出流：

paseo attach abc123   # Attach to agent (Ctrl+C to detach)

Agent ID 可以缩写，只要 abc 没有歧义就可以使用。

发送消息

向正在运行或空闲的 Agent 发送后续任务：

使用 paseo ls 中接收方的 Agent ID，或者从 Agent 的标签页复制。

paseo send <id> "now run the tests"
paseo send <id> --image screenshot.png "what's wrong here?"
paseo send <id> --no-wait "run this task"
paseo send <id> --behavior interrupt "stop and do this instead"

由 Agent 发起的发送（设置了 PASEO_AGENT_ID）默认引导正在进行的轮次。其他发送默认中断它。使用 --behavior steer 或 --behavior interrupt 覆盖默认行为。引导使用与客户端相同的后备方式：如果无法引导，正在进行的轮次会被中断并替换。

查看日志

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

等待 Agent

阻塞直到 Agent 完成当前任务：

paseo wait <id>
paseo wait <id> --timeout 60   # 60 second timeout

适用于脚本中，或一个 Agent 需要等待另一个 Agent 的情况。

定时任务

按 cron 定时任务运行 Agent。CLI 也接受简单的节奏预设，并把它们编译为 cron。完整参考见在 CLI 中使用定时任务。

paseo schedule create --every 30m --cwd ~/dev/my-app "Continue the refactor and leave a note."
paseo schedule ls
paseo schedule pause <id>

权限

Agent 在执行某些操作时可能会请求权限。在 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 模式

修改 Agent 的运行模式（因 Provider 而异）：

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

解除父子关系是一个显式的生命周期操作，而不是创建时的参数。Agent 会继续运行；只有它与父 Agent 的关系发生变化。

管理 daemon

定义一次实例，然后启动它保存的配置：

paseo daemon config set daemon.listen 127.0.0.1:6799 --home ~/paseo-test
paseo daemon config set daemon.relay.enabled false --home ~/paseo-test
paseo daemon start --home ~/paseo-test
paseo project ls --home ~/paseo-test
paseo daemon restart --home ~/paseo-test
paseo daemon stop --home ~/paseo-test

start 在后台运行，并报告实际的监听地址和进程管理器的 PID。它只接受主目录选择和 --timeout <seconds>（默认 600）。如果等待超时，进程管理器仍会继续运行：请使用输出的状态、日志和停止说明。worker 在就绪之前退出会导致启动失败。

restart 请求现有的进程管理器替换 worker。它会重新读取文件，并保留进程管理器原始的环境变量和参数。成功表示已有另一个 worker 就绪，对于主目录目标还会跟随已变更的地址。它从不启动已停止的 daemon，也不会刷新进程管理器的二进制文件。超时时会报告请求是否已被确认；它无法证明重连失败的原因。

stop --home 会等待该本地进程管理器退出。在 POSIX 上，它向进程管理器发送信号，不联系任何 TCP 端点。在 Windows 上，它使用已就绪 daemon 的关闭 RPC；未绑定的实例需要显式的 --force。--force 允许在正常关闭超时（默认 15 秒）后强制清理进程树。stop --host 只报告 shutdown requested；不会验证远程进程是否退出。在捕获的进程管理器退出后，服务管理器可能会启动另一个实例。

status 分别显示本地进程管理器的状态、它发布的端点、配置的地址和 RPC 可达性。已停止的主目录从不会在其配置的地址上被探测。未绑定但仍在运行的进程管理器显示为 not ready。如果经过身份验证的本地连接仍然打开，但状态详情超时，结果仍为 reachable，并附带一条说明详情不可用的备注。worker 和 Provider 字段会被省略。显式的 --host 查询在其状态请求失败时仍然会失败。

reload 校验文件、应用运行时安全的更改，并报告 appliedPaths、restartRequiredPaths 和 overrideControlledPaths。它从不会隐式重启。使用 --json 或 --format yaml 获得结构化结果。缺少这项能力的较旧主机会报告需要更新。

根级别名 start、status、restart、reload 和 pair 与 daemon 下的命令相同。根级的 run 和 stop 仍然是 Agent 操作。

前台部署与迁移

在前台部署命令中使用环境变量覆盖：

PASEO_LISTEN=127.0.0.1:6799 PASEO_RELAY_ENABLED=false paseo daemon run --home ~/paseo-test

它会一直保持附着，直到进程管理器退出或你取消，没有就绪超时。worker 重启会保留这些启动输入。要修改它们，请停止并重新启动部署。如果主目录中已经有一个运行中的进程管理器，run 会返回 already_running，而不会接管或启动前台进程。

托管的 start 会忽略继承来的 daemon 设置覆盖项，包括 PORT、PASEO_LISTEN、中继、语音和 Web UI 设置。它会保留 Provider 凭据以及可执行文件/运行时控制项。start --foreground 已被移除；请使用 daemon run。以前的 start/restart 配置参数，例如 --port、--no-relay 和 --web-ui，会在产生任何副作用之前失败，并给出相应的 config set 迁移方式。见配置编辑。

选择一个 daemon

每个连接 daemon 的 CLI 命令都接受全局的 --home 或 --host，放在命令之前或之后均可。主目录选择本地进程管理器发布的端点；主机选择一个显式的端点。不存在退回到配置地址或默认端口的行为。

选择器	结果
--home	该本地主目录，覆盖两个环境变量选择器
--host	该端点，覆盖两个环境变量选择器
同时提供两个参数，或重复且相互冲突的参数	TARGET_AMBIGUOUS
只有 PASEO_HOME 或只有 PASEO_HOST	对应的目标
两个环境变量选择器都存在，且没有参数	TARGET_AMBIGUOUS
都没有	默认的本地主目录 ~/.paseo

仅限本地的 start、daemon run、config、onboard 和 set-password 会拒绝显式的 --host，并忽略 PASEO_HOST。端点操作保留 TCP、Unix 套接字、Windows 管道、SSH 和配对信息等传输方式。在宿主机上控制容器的 CLI 需要 --host 或 PASEO_HOST。

Hub

paseo hub login [url]          # Approve and store organization-scoped CLI access
paseo hub init                 # Create and optionally deploy a starter trigger here
paseo hub connect [url]        # Enroll this daemon using CLI access
paseo hub projects             # List legacy projects in the authenticated organization
paseo hub status               # Show the current Hub relationship
paseo hub permissions list     # Show what this Hub may do on this daemon
paseo hub permissions grant hub.execute    # Let Hub automations run agents here
paseo hub permissions revoke hub.execute   # Take it back
paseo hub disconnect           # End it
paseo hub deploy               # Validate and install .paseo/triggers/*.yml
paseo hub deploy --dry-run     # Validate without installing
paseo hub deploy -p <project>   # Deploy an existing legacy project bundle
paseo hub logout               # Remove the active stored CLI login

请在仓库根目录运行 deploy。它默认按确定的路径顺序读取所有直接位于 .paseo/triggers/ 下的 *.yml 文件。它会先校验所有触发器，再逐个安装。如果在前面的安装成功之后某个安装失败，错误信息会列出已安装的文件。--dry-run 只做校验；它不会创建或激活修订。

对于已有的旧版文件包，传入 -p, --project <slug>：包括 .paseo/hub.yml、直接位于 .paseo/workflows/ 下的 *.yml 文件，以及被引用的 workflow 片段。见从 CLI 部署。

login 会打开 Hub 的批准页面，并在 PASEO_HOME 下保存一个持久的、组织范围的 CLI 凭据。在交互式终端中，它会提议连接这个 daemon，然后单独询问是否允许 Hub 自动化在这里运行 Agent。连接默认为是；执行权限默认为否。随后它会链接到 Hub 的 Triggers 页面，并输出 paseo hub init，以便用代码完成设置。--json 和非 TTY 的登录只执行登录，从不提示。保存的登录与 connect 创建的 daemon 关系是分开的。

init 需要 TTY。它会根据需要登录并连接 daemon，然后列出组织中可以支撑入门触发器的应用连接。只有一个可用连接时会自动选中；有多个时，由你选择一个 Trigger connection。如果没有任何连接就绪，设置会引导你前往 Hub → Apps，并在选择 Agent 或写入文件之前停止。

设置会询问要运行哪个 Agent Provider、模型和模式。Provider 必须已启用，并且同时提供可选择的模型和执行模式。建议的模型和模式条目是 daemon 的默认值；没有默认值时仍需显式选择模式。Hub 在部署前会对照 daemon 校验这项选择，并且其无人值守的运行只接受 Claude、Codex 和 OpenCode。deploy 会执行相同的检查，因此需要指定的 daemon 已连接。随后设置会询问允许触发机器人的身份：GitHub 用户名、Slack 成员 ID 或 Discord 用户 ID。它会校验触发器，写入 .paseo/triggers/<provider>-help.yml，并询问是否部署。替换该文件需要确认；已有的旧版文件包和其他触发器文件会被保留。见生成的入门触发器。

交互式退出会检查同一地址的 daemon 关系，并在删除登录之前询问是否断开。选择否时只删除登录。JSON 和非交互式的退出从不提示，也不会隐式断开；--disconnect-daemon 是供自动化使用的显式方式，--force 作用于该 daemon 断开操作。如果请求的断开失败，登录会被保留。

每个命令在执行 Hub 或 daemon 工作之前，都会解析并规范化它的目标。地址的优先级依次为：显式的命令地址或 --hub、PASEO_HUB_URL、当前保存的登录地址，最后是托管版默认地址 https://hub.paseo.sh。托管版默认地址从不会覆盖当前的登录。凭据的优先级依次为：--api-key <secret>、PASEO_HUB_API_KEY，然后是与解析出的地址完全匹配的已保存登录。保存的凭据从不会发送到其他地址。通过参数或环境变量传入的 API 密钥不会被保存。

人类可读的输出会在每个操作之前报告解析出的目标。JSON 输出让 stdout 保持机器可读，并包含规范化后的 Hub 地址。文件包诊断会指出路径，但不会输出配置内容或凭据。

见 Hub 中的 daemon、Hub 配置和 Hub 公开 API。

连接远程 daemon

全局的 --host 选项接受本地目标（host:port、Unix 套接字或 Windows 管道），也接受配对信息 URL，即移动应用在扫码配对时使用的同一个 https://app.paseo.sh/#offer=... 链接。使用配对信息 URL 时，CLI 会通过 Paseo 中继以端到端加密的方式连接，因此你可以驱动另一台机器上的 daemon，而不必把它暴露在网络上。

从你要控制的 daemon 获取配对信息 URL：

paseo daemon pair          # prints the QR and link when relay is enabled
paseo daemon pair --relay  # enables relay without prompting
paseo daemon pair --json   # structured output; never prompts

新安装默认关闭中继。中继被禁用时会返回 RELAY_DISABLED 错误；传入 --relay 表示明确同意。对于已停止的主目录，配对会被标记为离线；--relay 会保存中继启用设置，配对信息中会包含一条启动说明。运行中但不可达的主目录从不会退回到离线身份。中继配对是端到端加密的。见安全。

在任何地方使用它：

paseo --host 'https://app.paseo.sh/#offer=eyJ2IjoyLC...' ls
paseo --host "$OFFER_URL" run "fix the failing tests"

你也可以通过 PASEO_HOST 设置一次，而不必在每条命令中传入 --host。显式的参数会覆盖环境变量。

多 Agent 工作流

CLI 的设计初衷之一就是供 Agent 自己使用。你可以让一个 Agent 启动子 Agent 来并行工作：

# Agent A spawns Agent B and waits for it
agent_id=$(paseo run --no-wait --quiet --title api-agent "implement the API")
paseo wait "$agent_id"
paseo logs "$agent_id" --tail 5

由于 Agent A 的 ID 存在于环境变量中，除非指定了 --workspace，Agent B 会作为它的子 Agent 创建在同一个工作区中。

简单的实现加验证循环：

# 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

这种模式支持分层的任务分解：一个主导 Agent 可以拆分工作、委派给专门的 Agent，并汇总结果。

输出格式

大多数命令都支持多种输出格式，便于编写脚本：

paseo ls --json                # JSON output
paseo ls --format yaml         # YAML output
paseo ls -q                    # IDs only (quiet)

全局选项

• --host <target>，连接另一个 daemon（host:port、Unix 套接字，或用于中继的 https://app.paseo.sh/#offer=...）。见连接远程 daemon。
• --json，JSON 输出
• -q, --quiet，最少的输出
• --no-color，禁用颜色