302 lines
18 KiB
Markdown
302 lines
18 KiB
Markdown
# 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** runs, not only failures or the newest 50. Inside a pipeline,
|
|
`r` and `:runs` show only that pipeline's runs across its versions. In any run list,
|
|
press `/` for fuzzy search, type to filter, and Enter to return to the results.
|
|
Search includes pipeline name, version, status, outcome, stage and diagnostic;
|
|
`#123` searches run-ID prefixes. Esc while searching clears the filter without
|
|
closing the list. The filter survives inspection/back and live list refreshes.
|
|
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
|
|
|
|
```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
|
|
|
|
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. For unnamed drafts, submission asks you to
|
|
type a pipeline name directly in the TUI. Enter saves the name in retained metadata
|
|
and opens publication confirmation; it does not publish yet. Esc keeps the draft
|
|
without saving unfinished name input. 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:
|
|
|
|
```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` |
|
|
| 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:
|
|
|
|
```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`, `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 `--yes`, `--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 entire graph from the run's immutable
|
|
pinned version using the shared renderer and viewport. Executed stages and taken
|
|
routes retain their colors; unexecuted stages, unchosen routes and unreached
|
|
terminals are dimmed. Queued runs show the full graph before the first visit.
|
|
Repeated visits remain individually inspectable in the stage sidebar, while the
|
|
graph highlights every audited route through a loop. On small terminals details
|
|
take precedence. Older servers without a graph fall back to a matching loaded
|
|
definition or the recorded execution path, never a different pipeline/version. 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.”
|
|
|
|
In the run inspector, `n`/`p` select the next/previous recorded execution visit,
|
|
including repeated visits in loops, from any pane. Selection stops at the last
|
|
visit or overview; it does not wrap. The selected stage has a full-row highlight;
|
|
the focused stage/details pane has a highlighted title and pointer. In details,
|
|
the section containing the top visible row is highlighted and named in the pane
|
|
title. `Tab` cycles stages → details → graph (Shift+Tab reverses); `g` switches
|
|
graph focus. Each graph stage title shows live progress from its latest execution
|
|
visit. New run pages open with the graph focused and using roughly three quarters
|
|
of the available height. Tab expands the focused pane and contracts the others;
|
|
the stage list also widens when focused, and shrinks to a sidebar for details.
|
|
Pending stages are dimmed. The graph is centered horizontally/vertically
|
|
when it fits; the box-and-arrow diagram is retained at every viewport size,
|
|
never replaced with a stage list to fit. Oversized diagrams remain
|
|
pannable with `h/j/k/l` or arrows while the graph is focused; `c` recenters the
|
|
selected/current stage. `P` opens the
|
|
pinned pipeline (lowercase `p` remains an alias only on the runs list).
|
|
|
|
The pipeline page also gives most height to its focused graph or stage-details
|
|
pane; Tab switches focus and resizes the two panes. Focused titles use the same
|
|
background highlight as the run page.
|
|
Graph boxes are sized to their contents rather than the longest label anywhere
|
|
in the graph. Fork columns share only their own required width, route tracks are
|
|
adjacent, and branch spacing follows stacked boxes rather than tall trunk/merge
|
|
nodes. All stages, outcome labels, ports, and terminal arrows remain visible in
|
|
the full pannable diagram.
|
|
|
|
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. It asks for confirmation; `--yes` explicitly approves scripted deletion.
|
|
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.
|
|
|
|
```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` skips action confirmation for explicitly approved automation;
|
|
`--allow-tools` remains a compatibility flag and is 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 opens an action-confirmation popup before
|
|
starting with a live inspector (unless `--yes` was supplied). When a task is omitted,
|
|
Enter inserts a newline and Ctrl+S opens the confirmation for 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.
|
|
|
|
Run, retry, cancellation, CLI publication, and draft deletion require confirmation.
|
|
CLI prompts go to stderr and default to No; use `--yes` for non-interactive approval.
|
|
The TUI's run/retry/cancel popup accepts `y`; Enter does not implicitly approve,
|
|
and `n`/Esc cancels without sending the action. Retry restarts with new sessions
|
|
and original input/pwd, never the failed conversation; side effects may repeat.
|
|
Publication retains its explicit submission confirmation and version conflict guards.
|
|
Quit with `:quit`, not `q`; Ctrl+C remains an interrupt.
|
|
|
|
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**.
|