Files
pipelines/docs/cli.md
T

8.2 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. Optional autostart uses the OS user service manager directly. Legacy Python-managed installations require an explicit PIPELINES_PREFIX; no configuration is inferred from the executable's location. 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 new                               # OpenCode asks what to build and names it
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 opens OpenCode immediately when its name/request is omitted. The skill asks only for missing decisions and records the chosen name in draft metadata. edit accepts an exact name or ID, with names taking precedence over numeric IDs. Both retain private drafts and launch the host interface once with a short @pipelines reference and context-file path. There is no preliminary OpenCode API call, temporary service, session creation, or instruction preload. install.sh installs/updates the global skill and format reference. Plain go install users run pipelines skill install separately. Shared login/config and user-modified skills are preserved; OpenCode permissions remain in effect.

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.

Drafts in the TUI

Press d on the dashboard or use :drafts to browse the same retained drafts as pipelines drafts. Use n/p to select, j/k to scroll source, e/Enter to reopen the existing draft, v for server validation, and s for submission confirmation. r refreshes the list. Submission preserves create-only/version guards and rejects drafts belonging to another server. An unnamed draft must be named through OpenCode or CLI submit --name. Draft selection/editor completion never publishes it. New unnamed drafts open OpenCode so the skill can name them. For named drafts, the default editor is OpenCode; explicit VISUAL/EDITOR overrides remain.

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, retry_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

On either the runs list or run inspector, press p (or use :pipeline) to open the selected run's exact pipeline version. Navigation does not cancel the run.

Initial input includes pwd, the resolved run directory (normally the directory you invoked Pipelines from), alongside the task and any custom input fields. It is recorded by the server and shown in the run's Input section.

Press r or use :retry on a failed run to restart it from the first stage. CLI equivalent: pipelines retry <run-id> (optional --json, --wait, and --request-key). The new attempt retains the initial input, directory, pinned pipeline version, and edit scope, and records retry_of. Original history is unchanged. Legacy runs gain pwd from their recorded workspace on retry. Retry replays the entire workflow; earlier edits or notifications are not undone and may happen again. A missing original directory blocks retry rather than silently using your current directory.

cd ~/repos/project
pipelines run "bug fix" "Fix the layout" --json
pipelines run "bug fix" "Fix the layout" --json --wait --timeout 10m
pipelines run "bug fix" "Fix the layout" --json --request-key my-unique-task

Runs default to the client's current directory and latest accepted version. The server resolves that directory without a repository allowlist. --version chooses an immutable version in JSON mode. Starting a run enables its stage-declared tools without a second approval. Editing supports all file types and new files within the run directory; no file list is required. Shell commands use the repository's actual tooling. --write-paths is an optional narrower scope, not a prerequisite. --yes and --allow-tools remain compatibility flags but are not required. --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. A supplied pipeline/task starts immediately with a live inspector. When a task is omitted, Enter inserts a newline and Ctrl+S runs the composed task. There is no file-list question or typed RUN confirmation. Shell runs with your user's authority: the run directory and tool policy are not an OS sandbox.

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.