15 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.
Dashboard and status
Home's r opens all recent runs (latest 50), not only failures. Wide terminals
show runs and pipelines side by side, with stacked panels on narrow terminals.
Run cards show status, duration, start time and the current stage when active.
The usage summary is aggregated over all stored history, including retry attempts:
total/active runs, outcomes, success rate, average completed duration, pipeline
usage and a zero-filled 14-day daily activity chart (UTC). Success rate is
succeeded / (succeeded + failed); active, canceled and interrupted runs are excluded.
The average includes all runs with a finish timestamp. No model cost/token counts
are inferred from missing data. pipelines stats --json exposes these aggregates.
Use :status on any TUI page to open server and ntfy information. Scroll with
arrows or j/k, PgUp/PgDn; r refreshes and Esc closes without changing the page.
pipelines status [--json] returns the same server data, including hostname,
start/uptime, the connected server endpoint/port, active interface IPs, ntfy
publishing health, public phone URL/topic/port and candidate URLs. It does not
start services or send a notification. The ntfy health probe has a two-second
deadline; it checks the publishing server, not phone reachability.
IPs belong to the server computer or container, not necessarily the client.
Candidate IP/port combinations are not reachability checks: loopback bindings,
firewalls, container port mapping and TLS can prevent access. ntfy candidates
are only derived when a configured endpoint identifies this computer; remote
ntfy hosts are not misrepresented as local. Publishing URLs and credentials are
never returned. Missing public phone configuration is labeled explicitly.
pipelines service status remains the separate OS autostart status command.
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
Home's n / :new and Enter on a template first ask how to author the new
pipeline: nvim opens a retained Markdown draft file, or OpenCode opens
the collaborative harness with @pipelines. Tab/Shift+Tab or arrows select;
typing fuzzy-searches the choices; Enter launches and Esc cancels without
creating a draft. The choice overrides VISUAL/EDITOR. New drafts preserve
the create-only publication guard and still require explicit submission unless
you already published them from OpenCode. OpenCode can ask for a missing name;
for an unnamed nvim draft, pipelines submit <draft.md> --name NAME names and
publishes it. CLI pipelines new retains its existing direct-OpenCode behavior;
--no-open creates the file without launching an editor.
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.
On editor exit, the connected TUI checks the authoritative server before asking
to submit. If the draft source is already published (including a newer version
after the draft's base that was subsequently superseded), it skips confirmation
and reloads the latest pipeline/page and Home list. Local-only changes still need
explicit submission. A failed check retains the draft and says publication could
not be verified; it never assumes publication from an editor's exit code. Original
draft conflict guards and retained draft files remain unchanged.
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 |
| Server/ntfy status popup | status --json |
| Usage statistics/charts | stats --json |
| Legacy operational diagnostics | managed logs, 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, get_status. list_runs also returns all-history usage
aggregates. 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.
Retry is hidden and rejected while a run is executing or agent cleanup remains
active, even if a terminal status was already persisted. Run RPCs report
executing alongside status so clients can distinguish cleanup from completion.
The run inspector's upper half shows the actual execution path using the shared
pipeline graph renderer and viewport. Visits are numbered, including repeated
visits in loops; only recorded routing decisions become edges. No unchosen stage
is added to the run path. On small terminals the details take precedence. Press
g to focus the graph, arrows to pan, and j/k or PgUp/PgDn to scroll. Press g
or Tab to return to details. When not focused, the graph follows the latest visit
or selected stage. Existing polling refreshes the graph once per second, and
running durations show elapsed time rather than “in progress.”
Press a to select the active/latest retained OpenCode agent session and open its
tool evidence. Session ID is available during execution; tool transcripts appear
when persisted (currently after generation). This does not attach a live OpenCode
client or stream its messages. Supporting live attachment consistently across the
shared and privately owned OpenCode backends is deliberately deferred.
Investigating runs in OpenCode
On the runs list or inspector, press D or use :debug; CLI equivalent:
pipelines debug <run-id>. This opens a fresh normal OpenCode conversation, not
the implementing session. It supplies exact commands for inspect <run-id> --json (including stage history, inputs/outputs, diagnostics, notifications,
session IDs and transcripts), show <pipeline-id> --version N --json, and
runs --pipeline <pipeline-id> --json. All retrieval remains available through
the CLI and can be repeated while execution is active. No new model API or
live attachment integration is required.
debug --json returns the context and prompt without launching OpenCode;
--no-open prints the prompt. --opencode selects the executable. Debugging
works for active and terminal runs and does not automatically retry, cancel,
or resume them. If the recorded directory is unavailable, OpenCode launches
from your current directory and retrieves historical evidence through the CLI.
Editor choice and draft cleanup
On the pipeline detail page, e / :edit opens an editor picker: nvim or
OpenCode. Type to fuzzy-search; Tab/Shift+Tab (or arrows) choose; Enter opens;
Esc cancels without creating a draft. Explicit choice overrides VISUAL/EDITOR.
Both choices edit a retained copy with the normal version guard, never the
published definition. Submission remains separate and explicit.
In the draft browser, x asks to delete the selected draft; y confirms and
Esc or n keeps it. The CLI equivalent, pipelines draft-delete <draft.md>, is
an explicit deletion command and needs no server connection; --json reports
the result. Only managed drafts inside the configured draft cache are accepted.
Source and metadata symlinks/directories and external Markdown files are
rejected. Published definitions and run history are not deleted. Cleanup can
also remove orphaned metadata when a draft source was already removed.
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.