CLI

The shipplane-lite binary acts as both server and client. Once the server is running, you can control workflows from the terminal—useful for quick commands, scripts, and AI agents.

The CLI uses the same HTTP API as the UI and does not access the database directly.

Commands

shipplane-lite serve [--no-sync]              # start the HTTP server
shipplane-lite ls                             # list workflows
shipplane-lite run <workflow>                 # run one and stream its logs
shipplane-lite logs <workflow> [taskId] [-f]  # print stored logs; -f follows
shipplane-lite registry [--json]              # list task types and their params
shipplane-lite --version

Running shipplane-lite without a subcommand is equivalent to shipplane-lite serve.

<workflow> is normally the workflow id from your config file, not its database row ID. If no workflow ID matches and the argument contains only digits, the CLI treats it as a row ID.

Running a workflow

shipplane-lite run deploy-api

Logs stream as tasks produce them, prefixed with the task ID, and a progress line at the bottom tracks how many tasks are done:

[build] resolving 128 packages
[build] tsc --noEmit (2.4s)
[build] ✓ succeeded in 4.2s
[push] pushing ghcr.io/you/api:3f9c1a2
⠹ 1/4 done, 2 running

The command exits when the run reaches a final status. Its exit code reflects the outcome, so a command such as shipplane-lite run deploy-api && ./notify.sh only sends the notification after a successful run.

Press Ctrl-C once to cancel the run: the CLI sends a cancel request, keeps following until the run settles, then exits 130. Press it twice to detach immediately.

Read and follow logs

Task logs are stored in the run snapshot, so logs works during a run and after it finishes:

shipplane-lite logs deploy-api            # everything stored, then exit
shipplane-lite logs deploy-api -f         # attach to a run in progress
shipplane-lite logs deploy-api deploy     # one task only

With -f, the command prints stored logs, follows new output until completion, and exits with the run's outcome. You can therefore start a run in one process and wait for it in another:

shipplane-lite run deploy-api &
shipplane-lite logs deploy-api -f

Logs are capped per task

The runner keeps only the most recent logs.maxEntriesPerTask entries per task (default 100), discarding older ones as the run progresses. A long-running task's early output is gone by the time the run finishes, so a logs transcript is not a complete record. Raise the cap in the workflow definition's config.logs.maxEntriesPerTask if you need more history.

Discovering task types

Workflow definitions refer to task types and their parameters. registry reports the types registered on the running server, including custom task types from your config:

shipplane-lite registry

@shipplane/local_cmd  run a command on the local machine, like bash
  cmd          multiline command to execute locally
  cwd          string   working directory for the command
@shipplane/remote_cmd  run a command on a remote host over SSH
  cmd              multiline command to execute on the remote host
  ssh_host         string   hostname of the SSH server
  ssh_port         number   port of the SSH server
  ssh_user         string   username for the SSH connection
  ssh_private_key  string   private key path for the SSH connection
  allow_failure    boolean  succeed on a non-zero exit so dependent tasks can read the code from this task's output

Use registry --json to print the raw API response for generators, scripts, or agents.

Server address

The CLI resolves the server address in this order:

Order	Source
1	`--url <url>` flag
2	`SHIPPLANE_URL` environment variable
3	`http.addr` and `http.port` from your config file
4	`http://127.0.0.1:3000`

If your config uses port 3300, shipplane-lite ls connects to that port without an additional flag. Use --url to connect to a different server for one command:

shipplane-lite --url http://10.0.0.5:3000 ls

Because http.addr is a bind address, 0.0.0.0 and :: are rewritten to 127.0.0.1 when building the request URL.

Exit codes

Code	Meaning
`0`	Workflow succeeded, or a read command completed
`1`	Workflow failed, was cancelled, or paused; or the server was unreachable
`2`	Missing or unknown argument, or an unrecognized workflow
`130`	Interrupted with `Ctrl-C`

Use from scripts and agents

Output adapts to its destination. In a terminal, the CLI displays color and a live progress line. When piped, it omits color, escape codes, and redrawn frames so programs can process the output:

shipplane-lite run deploy-api | grep '^\[deploy\]'
shipplane-lite run deploy-api | tee deploy.log

Errors are written to stderr; task logs are written to stdout.

Editing workflows

The CLI does not provide create or edit commands. Define workflows in your config file and seed them when serve starts, or edit them in the UI.

Restart the server after changing a workflow in your config. You can automate restarts with a file watcher:

nodemon --watch ~/.config/shipplane --exec 'shipplane-lite serve'

#CLI

#Commands

#Running a workflow

#Read and follow logs

#Discovering task types

#Server address

#Exit codes

#Use from scripts and agents

#Editing workflows

CLI