# 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 ```sh 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: ```sh 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: ```sh 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 ```sh 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**.