6.1 KiB
CLI and agent authoring
pipelines help lists commands; pipelines help edit (or edit --help) shows
command-specific flags and examples. Installed commands work from any directory.
The installed command is a compiled Go binary; only service lifecycle management
delegates to the private Python helper. The binary discovers its manifest through
the system command symlink. A separately go install ./cmd/pipelines-installed
binary can select a managed installation using PIPELINES_PREFIX.
For source development, use go run ./cmd/pipelines help; start the native server
separately. Set PIPELINES_URL or pass --url to select another server.
Draft-first OpenCode workflow
pipelines edit # fuzzy pipeline selection
pipelines edit "bug fix" # ask OpenCode what to change
pipelines edit "bug fix" "Add a review step"
pipelines new "release notes" "Summarize changes and notify my phone"
pipelines new "weekly digest" --template scheduled-summary
new asks for a name when omitted. edit accepts an exact name or ID, with names
taking precedence over numeric IDs. Both copy a definition into a private draft
and launch the host OpenCode interface. An isolated authoring workspace contains
the bundled pipelines skill and format reference. The CLI creates an OpenCode
session and explicitly activates the skill with resume=false before opening
the interface. It does not modify shared OpenCode configuration or copy login
credentials. Your OpenCode permissions remain in effect; auto-approval is not used.
The skill encourages editing only the draft, running server validation, summarizing
the changes, and leaving submission to the user. This is an instruction, not a
security sandbox: an agent with CLI/shell access can submit when explicitly asked.
Every submission, including agent-issued submit/rpc, still uses server validation.
For agents or scripts that should not open a terminal:
pipelines new "release notes" --no-open
pipelines edit "bug fix" --json
pipelines drafts --json
pipelines validate /path/to/pipeline-123.md --json
pipelines submit /path/to/pipeline-123.md --json
--json never opens an editor or picker; provide a name explicitly. It returns
draft metadata including path, name, server, create_only, and base_version.
--no-open prints the path and review commands. $PIPELINES_DRAFT_DIR overrides
the shared cache directory. CLI and TUI drafts use private Markdown plus metadata
sidecars; submit FILE can publish either. External files require --name NAME.
New drafts use create-only submissions and cannot overwrite existing names.
Edits carry a latest-version guard checked atomically by the server. On conflict,
inspect/export the latest version and reconcile the draft. --force explicitly
bypasses the version guard only, never syntax, graph, model, tool, schedule,
or notification validation. Original versions/sources remain immutable.
Submitting activates included schedules, so review them before publishing.
CLI/TUI capability map
| TUI action | Agent-capable CLI |
|---|---|
| Browse/search pipelines | list --json, show NAME --json |
| Original source and history | export NAME --version N, versions NAME --json |
| Browse templates/source | templates --json, template KEY --source |
| Create or edit a definition | new, edit, drafts |
| Validate and publish | validate FILE, submit FILE |
| Start a run | run NAME PROMPT --yes --json |
| Run history/inspection | runs --json, inspect ID --json |
| Cancel | cancel ID --json |
| Connection and phone settings | connection --json, ping --json |
| Operational diagnostics | installed logs, status, doctor |
The TUI does not spawn CLI processes for each request. Both front ends share
internal/client's command transport and internal/draft's persisted drafts;
the server owns all validation, persistence, execution, and schedules. rpc
exposes the full protocol as an escape hatch, so no server command is TUI-only:
printf '%s' '{"type":"get_pipeline","pipeline_id":1,"version":1}' | pipelines rpc -
Existing protocol commands: ping, list_pipelines, get_pipeline,
list_templates, validate, submit, run_pipeline, list_runs, get_run,
cancel_run. See internal/protocol/message.go for JSON envelopes. Mutating RPCs
have real effects; they are not previews. TUI-only animation, scrolling, and
transient client logs are presentation, not separate server capabilities.
Scripted runs
cd ~/repos/project
pipelines run "bug fix" "Fix the layout" --yes --json
pipelines run "bug fix" "Fix the layout" --yes --json --wait --timeout 10m
pipelines run "bug fix" "Fix the layout" --yes --json \
--allow-tools --write-paths internal/example.go --request-key my-unique-task
Runs default to the current directory and latest accepted version. The server
checks allowed workspace roots, including symlink resolution. --version chooses
an immutable version in JSON mode. --yes never grants tools implicitly.
Go-specific file editing and restricted Go shell checks remain in effect.
--wait polls until terminal status, returns nonzero on failure/cancellation,
and does not cancel a run when waiting times out. Reuse --request-key to prevent
duplicate work. Without JSON, run opens the existing interactive composer and
live inspector; Enter inserts a newline, Ctrl+S continues.
JSON results go to stdout, errors to stderr (JSON error envelopes when requested),
and failures exit nonzero. Export/template --source deliberately prints raw
Markdown. --timeout bounds each server request and the optional wait duration.
Verification scope
CLI integration tests exercise draft/validate/submit/history/conflict handling and scripted run/inspection/cancellation through a real local WebSocket server (the run test uses a controlled executor, not a model). The isolated installed CLI also exercised the actual OpenCode API's session creation and skill activation, while capturing interactive launch arguments to avoid a model turn. Full model-driven authoring and Linux execution are not tested.