spool command reference

Every command, its flags and examples. spool <command> --help prints the same.

spool submit

The same command as spool run submit.

spool ls

The same command as spool run list.

spool logs

The same command as spool run logs.

spool approve

The same command as spool approval approve.

spool reject

The same command as spool approval reject.

Usage: spool login [OPTIONS] <SERVER-URL>

spool login https://api.hyperspool.dev  # prompts for a token
spool login https://api.hyperspool.dev --scope acme/web < token.txt
spool login http://127.0.0.1:18753 --name laptop

<SERVER-URL>: The server, e.g. https://hyperspool.dev
--name <LOGIN>: Name the login (default the server’s host)
--scope <ORG[/PROJECT]>: The org and project to use (default your only one, or a prompt)
--context-name <N>: Name the context it saves (default the login’s name)
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

The token is read from stdin, or prompted for without echo on a terminal. With several orgs and no –scope, it asks which; with no terminal it exits 2 and asks for –scope.

spool logout

Forget a login’s token

Usage: spool logout [OPTIONS] [LOGIN]

spool logout  # the current context's login
spool logout hyperspool.dev --yes

<LOGIN>: The login (default the current context’s)
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool init

Write starter workflows

Usage: spool init [OPTIONS] [DIR]

spool init  # starter workflows in this directory
spool init ci  # in ./ci

<DIR>: Where to write them (default .)

spool dev

Hyperspool on this machine: server, agent and console

Usage: spool dev [OPTIONS]
       spool dev <COMMAND>

spool dev  # server, agent and console on this machine
spool dev --port 18800 --name scratch  # a second one beside it
spool dev --db ./dev.db  # keep its runs between restarts

--port <N>: Listen on this port
--bind <ADDR>: Listen on this address
--db <PATH>: Keep the database at PATH
--name <CONTEXT>: Register as this context (default local)
--no-register: Don’t register a context

spool dev up

Start the server, agent and console here

Usage: spool dev up [OPTIONS]

spool dev up  # the same as `spool dev`

--port <N>: Listen on this port
--bind <ADDR>: Listen on this address
--db <PATH>: Keep the database at PATH
--name <CONTEXT>: Register as this context (default local)
--no-register: Don’t register a context

spool inbox

What needs you: approvals, stuck runs, recent failures

Usage: spool inbox [OPTIONS]

spool inbox  # approvals, stuck runs and failures
spool inbox -o json  # the whole inbox for a script

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

-o json prints the inbox itself: approvals, runs no agent can take, and recent failures. -o id is refused, because the three have no common id.

spool open

Open the console at a page or a run

Usage: spool open [OPTIONS] [PAGE|RUN]

spool open  # the project's console page
spool open acme:web:run-7Hk2  # a run's page
spool open schedules --print  # print the URL instead

<PAGE|RUN>: A console page, or a run (default the project’s front page)
--print: Print the URL instead of opening it
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool version

This client’s version, and the server’s

Usage: spool version [OPTIONS]

spool version  # this client and the server
spool version --client  # this client only; offline

--client: Only this client’s version; asks no server
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool feedback

Send feedback to the Hyperspool team

Usage: spool feedback [OPTIONS] <TEXT>...

spool feedback the logs view drops the last line
spool feedback --category bug run rerun ignores --from

<TEXT>: What you want to say
--category <C>: bug, feature, criticism, question or other
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool completion

Print a shell completion script

Usage: spool completion [OPTIONS] <SHELL>

spool completion bash > ~/.local/share/bash-completion/completions/spool
spool completion zsh > ~/.zfunc/_spool
spool completion nushell

<SHELL>: The shell

spool man

Write man pages

Usage: spool man [OPTIONS]

spool man | man -l -  # read the top page
spool man --dir ~/.local/share/man/man1  # one page per command

--dir <PATH>: Write one page per command into PATH, instead of spool.1 on stdout

spool run

Runs: list, watch, cancel, rerun, explain; or run a file here

Usage: spool run [OPTIONS] [FILE]
       spool run <COMMAND>

spool run list  # recent runs
spool run ci.yaml  # run a file on a throwaway local server
spool run ./list  # a file named like a verb

<FILE>: A pipeline, graph or script to run here; - reads stdin
--as <KIND>: pipeline, graph or script (read from the file when left out)
--input <JSON>: Run input: inline JSON, @file or -
--tag <TAG>: Tag the run (repeatable)
-f, --follow: Watch it in the TUI
--db <PATH>: Keep the run’s database at PATH

spool run list

Recent runs in the project

Usage: spool run list [OPTIONS]

spool run list  # the newest runs
spool run list --status failed --status cancelled
spool run list --tag branch:main --limit 5 -o id
spool run list --waiting  # what each running run waits for
spool run list --all -o json  # every run, as JSON

--tag <TAG>: Only runs with this tag (repeatable; all must match)
--status <STATUS>: Only runs in this status (repeatable)
--dry: Dry runs instead of real ones
--waiting: Add a WAITING column: what each running run waits for
--limit <N>: Rows per page
--cursor <C>: Start from this cursor, from a previous page’s more: hint
--all: Fetch every page
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run get

One run’s status, output and error

Usage: spool run get [OPTIONS] <RUN>

spool run get run-7Hk2
spool run get acme:web:run-7Hk2 -o json

<RUN>: The run: its id, qualified id or console URL
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run submit

Start a run from a file, a stored workflow, one node, or a repository

Usage: spool run submit [OPTIONS] [FILE]
       spool submit [OPTIONS] [FILE]

spool submit ci.yaml  # a pipeline; prints the run id
spool submit deploy.py -f  # a script, watched until it ends
spool submit -w release --input @in.json --wait
spool submit --node http --config @req.json  # one node on its own
spool submit --repo acme/web --repo-path .spool/ci.yaml --repo-credential gh --ref main

<FILE>: A pipeline, graph or script; - reads stdin
-w, --workflow <NAME[@V]>: A stored workflow; published unless @V
--node <KIND>: One node kind (spool node list)
--repo <REPO>: The pipeline at –repo-path in a repository
--input <JSON>: Run input: inline JSON, @file or -
--tag <TAG>: Tag the run (repeatable)
--name <NAME>: What a script run is listed as
--as <KIND>: pipeline, graph or script
--interpreter <CMD>: Run a script with this interpreter
--credential <ENV=NAME>: A project credential in a script’s env (repeatable)
--config <JSON>: Node config (with –node): inline JSON, @file or -
--nodes <JSON>: Upstream outputs for a lifted node
--repo-path <PATH>: The pipeline’s path (with –repo)
--ref <REF>: Branch, tag or sha (with –repo)
--repo-credential <NAME>: Credential to read the repo (with –repo)
--forge <KIND>: Forge connection kind (default github)
--concurrency-group <G>: Share a concurrency limit with runs in group G
--concurrency-policy : What a full group does with this run
--concurrency-queue-max <N>: How many runs a group queues
--throttle <LIMIT/PERIOD>: At most LIMIT starts per PERIOD, e.g. 10/1m
--throttle-key <K>: Throttle per value of K
--throttle-burst <N>: Starts allowed at once above the rate
--throttle-policy : What a throttled run does
--cancel-on <TYPE>: Cancel the run when an event of TYPE arrives (repeatable)
--idempotency-key <K>: Submitting again with the same K returns the first run
-f, --follow: Watch until it ends: the TUI on a terminal, the log otherwise
--wait: Block until it ends
--timeout <DUR>: Stop watching after DUR and exit 124
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

Exit status: 0 accepted (watching: completed), 1 the run failed, 2 usage, 5 not allowed, 6 unreachable, 124 timed out.

spool run logs

A run’s output (-f tails it)

Usage: spool run logs [OPTIONS] <RUN>

spool logs run-7Hk2  # what it printed so far
spool logs run-7Hk2 --all  # all of it, every line named by its step
spool logs run-7Hk2 -f  # follow; exit with the run's outcome
spool logs run-7Hk2 -f --timeout 10m

<RUN>: The run
--all: The whole log, every line named by its step
-f, --follow: Keep printing until the run ends, then exit with its outcome
--timeout <DUR>: Stop after DUR and exit 124
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

Prints the run’s output as text. With -f it keeps printing until the run ends and exits with its outcome: 0 completed, 1 failed or cancelled.

spool run follow

Watch a run to its end: the TUI, or its log in a pipe

Usage: spool run follow [OPTIONS] <RUN>

spool run follow run-7Hk2
spool run follow run-7Hk2 --timeout 1h

<RUN>: The run
--timeout <DUR>: Stop waiting after DUR and exit 124
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run why

Why a run is where it is: what it waits for, or why it failed

Usage: spool run why [OPTIONS] <RUN>

spool run why run-7Hk2  # what it waits for, or why it failed

<RUN>: The run: its id, qualified id or console URL
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run events

A run’s event history

Usage: spool run events [OPTIONS] <RUN>

spool run events run-7Hk2
spool run events run-7Hk2 -f -o json  # NDJSON as they happen

<RUN>: The run: its id, qualified id or console URL
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command
-f, --follow: Keep printing events as they happen

Prints text, or one JSON object per line with -o json.

spool run steps

A run’s steps and their outcomes

Usage: spool run steps [OPTIONS] <RUN>

spool run steps run-7Hk2

<RUN>: The run: its id, qualified id or console URL
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run activities

A run’s activities

Usage: spool run activities [OPTIONS] <RUN>

spool run activities run-7Hk2
spool run activities run-7Hk2 --failed

<RUN>: The run: its id, qualified id or console URL
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command
--failed: Only the activities that failed

spool run annotations

A run’s annotations

Usage: spool run annotations [OPTIONS] <RUN>

spool run annotations run-7Hk2 -o json

<RUN>: The run: its id, qualified id or console URL
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run step-output

One step’s recorded output

Usage: spool run step-output [OPTIONS] <--node <ID>|--site <SITE>> <RUN>

spool run step-output run-7Hk2 --node fetch  # a graph node's output
spool run step-output run-7Hk2 --site build --ordinal 2

<RUN>: The run: its id, qualified id or console URL
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command
--node <ID>: A graph node’s id
--site <SITE>: A script step’s name
--ordinal <N>: Which pass through the site (default the last)

spool run signal

Send a signal to a waiting run

Usage: spool run signal [OPTIONS] <RUN> <SIGNAL>

spool run signal run-7Hk2 deploy-approved
spool run signal run-7Hk2 go --payload '{"env":"prod"}' --wait

<RUN>: The run
<SIGNAL>: The signal’s name, as the run waits for it
--payload <JSON>: The signal’s payload: inline JSON, @file or -
-f, --follow: Watch until it ends: the TUI on a terminal, the log otherwise
--wait: Block until it ends
--timeout <DUR>: Stop watching after DUR and exit 124
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run cancel

Cancel a run

Usage: spool run cancel [OPTIONS] <RUN>

spool run cancel run-7Hk2
spool run cancel run-7Hk2 --reason 'wrong branch'

<RUN>: The run
--reason <TEXT>: Why, shown on the run’s page
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run rerun

Run a finished run again

Usage: spool run rerun [OPTIONS] <RUN>

spool run rerun run-7Hk2
spool run rerun run-7Hk2 --from deploy -f  # reuse what came before deploy

<RUN>: The run
--from <POINT>: Start from this step, reusing what came before it
--from-family <FAMILY>: Which kind of point –from is (step, wait, …), if two share its name
--no-tags: Don’t copy the run’s tags
-f, --follow: Watch until it ends: the TUI on a terminal, the log otherwise
--wait: Block until it ends
--timeout <DUR>: Stop watching after DUR and exit 124
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool run open

Open a run in the console

Usage: spool run open [OPTIONS] <RUN>

spool run open run-7Hk2
spool run open run-7Hk2 --print

<RUN>: The run
--print: Print the URL instead of opening it
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool approval

Approvals waiting for someone

Usage: spool approval [OPTIONS] <COMMAND>

spool approval list
spool approve run-7Hk2

spool approval list

Approvals waiting for someone

Usage: spool approval list [OPTIONS]

spool approval list
spool approval list -o json

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool approval approve

Approve a waiting run

Usage: spool approval approve [OPTIONS] <RUN> [GATE]

spool approve run-7Hk2  # prompts for the fields it asks
spool approve run-7Hk2 release --field version=1.4.2
spool approve run-7Hk2 --payload @answer.json --no-prompt --wait

<RUN>: The waiting run
<GATE>: The gate, when the run waits at more than one
--field <NAME=VALUE>: Answer a field the approval asks for (repeatable)
--payload <JSON>: The whole answer: inline JSON, @file or -
--no-prompt: Don’t prompt for fields left out; fail instead
-f, --follow: Watch until it ends: the TUI on a terminal, the log otherwise
--wait: Block until it ends
--timeout <DUR>: Stop watching after DUR and exit 124
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool approval reject

Turn an approval down; the run fails at the gate

Usage: spool approval reject [OPTIONS] <RUN> [GATE]

spool reject run-7Hk2
spool reject run-7Hk2 release --reason 'not this week'

<RUN>: The waiting run
<GATE>: The gate, when the run waits at more than one
--reason <TEXT>: Why, shown on the run’s page
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool chat

Answer approvals from Slack or Mattermost

Usage: spool chat [OPTIONS] <COMMAND>

spool chat list
spool chat links  # the chat accounts linked to you

spool chat list

Where the project’s approvals are posted

Usage: spool chat list [OPTIONS]

spool chat list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool chat get

One chat target

Usage: spool chat get [OPTIONS] <NAME>

spool chat get releases

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool chat set

Post the project’s approvals to a Slack or Mattermost channel

Usage: spool chat set [OPTIONS] --channel <CHANNEL> --credential <NAME> <NAME>

printf %s "$SIGNING_SECRET" | spool chat set releases --slack --channel C0123ABCD --credential slack-bot --signing-secret
spool chat set releases --slack --channel C0123ABCD --credential slack-bot --when 'event.payload.workflow_name == "release"'  # keeps the secret
spool chat set ops --mattermost --server-url https://chat.example.com --channel 4xk9s1 --credential mm-bot

<NAME>: The target’s name
--slack: Post to Slack
--mattermost: Post to Mattermost
--channel <CHANNEL>: The channel’s id (on Slack, a name the bot can post to works too)
--credential <NAME>: The project credential holding the bot’s token (bearer)
--server-url <URL>: The Mattermost server; for Slack only off slack.com
--signing-secret: Read Slack’s signing secret from stdin or a prompt (needed once)
--when <EXPR>: Post only approvals this CEL over the run.awaiting event admits
--match-email: Also know a chat user by the email the platform reports
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool chat delete

Stop posting to a channel

Usage: spool chat delete [OPTIONS] <NAME>

spool chat delete releases

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool chat messages

A target’s recent messages: posted, answered, or stuck and why

Usage: spool chat messages [OPTIONS] <NAME>

spool chat messages releases  # posted, answered, or stuck and why

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool chat link

Link the chat account a code names to you

Usage: spool chat link [OPTIONS] <CODE>

spool chat link hscl_4f2a9c  # the code a chat message gave you

<CODE>: The code a chat message gave you (hscl_…)
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool chat links

The chat accounts linked to you

Usage: spool chat links [OPTIONS]

spool chat links

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool chat unlink

Unlink one of your chat accounts

Usage: spool chat unlink [OPTIONS] <ID>

spool chat unlink slack/T0123/U0456

<ID>: The link, as spool chat links shows it: platform/workspace/user
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool workflow

Workflows and their stored definitions

Usage: spool workflow [OPTIONS] <COMMAND>

spool workflow list
spool workflow set release release.yaml --publish
spool workflow check .spool/*.yaml

spool workflow list

The project’s workflows and how their runs went

Usage: spool workflow list [OPTIONS]

spool workflow list  # how each workflow's runs went
spool workflow list --stored  # stored workflows and their versions

--stored: Stored workflows and their draft and published versions
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow get

One workflow and how its runs went

Usage: spool workflow get [OPTIONS] <NAME>

spool workflow get release

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow versions

A stored workflow’s versions

Usage: spool workflow versions [OPTIONS] <NAME>

spool workflow versions release

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow export

Print a stored workflow’s document

Usage: spool workflow export [OPTIONS] <NAME[@V]>

spool workflow export release > release.yaml  # the published version
spool workflow export release@draft --format json

<NAME[@V]>: The workflow, and a version (default @published)
--format <FORMAT>: yaml or json
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

Prints the workflow’s document, not a table: YAML unless –format json.

spool workflow set

Store a workflow as a new draft

Usage: spool workflow set [OPTIONS] <NAME> <FILE>

spool workflow set release release.yaml  # a new draft
spool workflow set release release.yaml --publish
cat release.json | spool workflow set release -

<NAME>: The workflow’s name
<FILE>: The document; - reads stdin
--publish: Publish it too
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

With –publish, a webhook trigger’s secret is minted and shown once. In a pipe stdout is then the secret alone and the name goes to stderr; -o id is refused.

spool workflow edit

Edit a stored workflow’s draft in $VISUAL or $EDITOR

Usage: spool workflow edit [OPTIONS] <NAME>

spool workflow edit release  # the draft, in $VISUAL or $EDITOR
spool workflow edit release --publish

<NAME>: The workflow’s name
--publish: Publish it when the editor closes
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow publish

Publish a draft, so runs and triggers use it

Usage: spool workflow publish [OPTIONS] <NAME[@V]>

spool workflow publish release  # the draft
spool workflow publish release@3  # only while the draft is v3

<NAME[@V]>: The workflow, and a version: @3, @draft or @published
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

Publishing a workflow with a webhook trigger mints the trigger’s secret, shown once. In a pipe stdout is then the secret alone and the name goes to stderr; -o id is refused.

spool workflow try

Dry-run a workflow: nothing outside the run changes

Usage: spool workflow try [OPTIONS] <NAME[@V]|FILE>

spool workflow try release  # the draft, as a dry run
spool workflow try release --seed-from run-7Hk2
spool workflow try ./release.yaml --input @in.json

<NAME[@V]|FILE>: A stored workflow (default @draft), or a file; - reads stdin
--seed-from <RUN>: Reuse this run’s recorded step outputs
--input <JSON>: Run input: inline JSON, @file or -
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow delete

Delete a stored workflow and all its versions

Usage: spool workflow delete [OPTIONS] <NAME>

spool workflow delete old-release
spool workflow delete old-release --yes

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow open

Open a workflow in the console

Usage: spool workflow open [OPTIONS] <NAME>

spool workflow open release
spool workflow open release --print

<NAME>: Its name
--print: Print the URL instead of opening it
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow stats

How long each step of a workflow takes

Usage: spool workflow stats [OPTIONS] <NAME>

spool workflow stats release
spool workflow stats deploy --patterns

<NAME>: The workflow’s name
--patterns: The script call patterns instead of step timings
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow requirements

What a workflow needs: capabilities, credentials, secrets

Usage: spool workflow requirements [OPTIONS] <NAME[@V]>

spool workflow requirements release@draft

<NAME[@V]>: The workflow, and a version: @3, @draft or @published
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow sources

Where a workflow’s runs come from

Usage: spool workflow sources [OPTIONS] <NAME>

spool workflow sources release

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool workflow check

Check workflow files for mistakes, offline

Usage: spool workflow check [OPTIONS] <FILE>...

spool workflow check ci.yaml
spool workflow check .spool/ci.yaml .spool/release.yaml -o json

<FILE>: Files to check; - reads one from stdin
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool workflow render

Draw a workflow file as text, offline

Usage: spool workflow render [OPTIONS] <FILE>

spool workflow render ci.yaml
spool workflow render graph.json --summary

<FILE>: The file to draw
--summary: One line per step instead of the drawing

spool schedule

Runs on an interval or a cron expression

Usage: spool schedule [OPTIONS] <COMMAND>

spool schedule list
spool schedule create nightly.yaml --cron '0 0 3 * * *'

spool schedule list

The project’s schedules

Usage: spool schedule list [OPTIONS]

spool schedule list
spool schedule list -o id

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool schedule get

One schedule and its recent fires

Usage: spool schedule get [OPTIONS] <ID>

spool schedule get sch-4kQ

<ID>: Its id
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool schedule create

Create a schedule

Usage: spool schedule create [OPTIONS] <FILE|-w <NAME[@V]>|--node <KIND>>
       <--every <DUR>|--cron <EXPR>>

spool schedule create nightly.yaml --cron '0 0 3 * * *' --tz Europe/Stockholm
spool schedule create -w backup --every 6h --overlap skip
spool schedule create --node http --config @ping.json --every 5m

<FILE>: A pipeline or script file; - reads stdin
--as <KIND>: pipeline or script (read from the file when left out)
-w, --workflow <NAME[@V]>: A stored workflow; published unless @V
--node <KIND>: One node kind
--config <JSON>: Node config (with –node): inline JSON, @file or -
--every <DUR>: Fire every DUR
--cron <EXPR>: Fire on a 6-field cron expression, seconds first
--tz <ZONE>: The cron expression’s time zone (default UTC)
--overlap <MODE>: What a fire does while the last one still runs
--jitter <DUR>: Fire up to DUR late, at random
--name <NAME>: What the schedule is listed as
--tag <TAG>: Tag its runs (repeatable)
--requires <CAP>: A capability its runs need (repeatable)
--input <JSON>: Run input: inline JSON, @file or -
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool schedule update

Change a schedule; flags left out keep their values

Usage: spool schedule update [OPTIONS] <ID> [FILE]

spool schedule update sch-4kQ --every 12h
spool schedule update sch-4kQ --clear jitter

<ID>: The schedule
<FILE>: A pipeline or script file; - reads stdin
--as <KIND>: pipeline or script (read from the file when left out)
-w, --workflow <NAME[@V]>: A stored workflow; published unless @V
--node <KIND>: One node kind
--config <JSON>: Node config (with –node): inline JSON, @file or -
--every <DUR>: Fire every DUR
--cron <EXPR>: Fire on a 6-field cron expression, seconds first
--tz <ZONE>: The cron expression’s time zone (default UTC)
--overlap <MODE>: What a fire does while the last one still runs
--jitter <DUR>: Fire up to DUR late, at random
--name <NAME>: What the schedule is listed as
--tag <TAG>: Tag its runs (repeatable)
--requires <CAP>: A capability its runs need (repeatable)
--input <JSON>: Run input: inline JSON, @file or -
--clear <FIELD>: Clear a field back to its default (repeatable)
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool schedule run

Fire a schedule now

Usage: spool schedule run [OPTIONS] <ID>

spool schedule run sch-4kQ  # fire it now
spool schedule run sch-4kQ --alongside -f

<ID>: The schedule
--alongside: Fire even while its last run is still going
-f, --follow: Watch until it ends: the TUI on a terminal, the log otherwise
--wait: Block until it ends
--timeout <DUR>: Stop watching after DUR and exit 124
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool schedule pause

Stop a schedule firing

Usage: spool schedule pause [OPTIONS] <ID>

spool schedule pause sch-4kQ

<ID>: Its id
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool schedule resume

Let a paused schedule fire again

Usage: spool schedule resume [OPTIONS] <ID>

spool schedule resume sch-4kQ

<ID>: Its id
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool schedule delete

Delete a schedule

Usage: spool schedule delete [OPTIONS] <ID>

spool schedule delete sch-4kQ
spool schedule delete sch-4kQ --yes

<ID>: Its id
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool schedule open

Open a schedule in the console

Usage: spool schedule open [OPTIONS] <ID>

spool schedule open sch-4kQ

<ID>: Its id
--print: Print the URL instead of opening it
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool handler

Runs when a matching event arrives

Usage: spool handler [OPTIONS] <COMMAND>

spool handler list
spool handler set deploy deploy.sh --on github.push

spool handler list

The project’s event handlers

Usage: spool handler list [OPTIONS]

spool handler list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool handler get

One handler

Usage: spool handler get [OPTIONS] <NAME>

spool handler get deploy

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool handler set

Create or replace a handler

Usage: spool handler set [OPTIONS] --on <TYPES> <NAME>
       <FILE|-w <NAME[@V]>|--node <KIND>>

spool handler set deploy deploy.sh --on github.push --when 'event.ref == "refs/heads/main"'
spool handler set notify -w notify --on 'run.failed,run.cancelled'
spool handler set ci ci.sh --on github.pull_request.opened --credential GH_TOKEN=gh

<NAME>: The handler’s name
<FILE>: A pipeline or script file; - reads stdin
--as <KIND>: pipeline or script (read from the file when left out)
-w, --workflow <NAME[@V]>: A stored workflow; published unless @V
--node <KIND>: One node kind
--config <JSON>: Node config (with –node): inline JSON, @file or -
--on <TYPES>: Event types to handle, comma-separated patterns
--when <CEL>: Only events this CEL expression accepts
--tag <TAG>: Tag its runs (repeatable)
--requires <CAP>: A capability its runs need (repeatable)
--credential <ENV=NAME>: A project credential in the script’s env (repeatable)
--optional-when-untrusted: Run for untrusted events too, without the credentials
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool handler delete

Delete a handler

Usage: spool handler delete [OPTIONS] <NAME>

spool handler delete deploy
spool handler delete deploy --yes

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool handler init

Write a starter handler script, offline

Usage: spool handler init [OPTIONS] [NAME] [FILE]

spool handler init  # list the templates
spool handler init deploy-on-tag  # write deploy-on-tag.sh
spool handler init ci-router ci/router.sh
spool handler init notify -  # print it

<NAME>: A template’s name; left out, lists them
<FILE>: Where to write it (default NAME.sh; - prints it); never overwrites

spool webhook

Incoming HTTP deliveries, turned into events

Usage: spool webhook [OPTIONS] <COMMAND>

spool webhook list
spool webhook set stripe --event-type stripe.event

spool webhook list

The project’s incoming webhooks

Usage: spool webhook list [OPTIONS]

spool webhook list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool webhook get

One webhook and its ingest URL

Usage: spool webhook get [OPTIONS] <NAME>

spool webhook get stripe  # its ingest URL

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool webhook set

Create or replace a webhook

Usage: spool webhook set [OPTIONS] <NAME>

spool webhook set stripe --event-type stripe.event  # mints a secret, printed once
printf %s "$KEY" | spool webhook set shop --event-type shop.order --hmac-header X-Signature --hmac-prefix sha256=
spool webhook set forge --manifest github --trust-actor octocat

<NAME>: The webhook’s name
--event-type <TYPE>: The event type deliveries become
--manifest <NAME>: Verify deliveries with a sender’s manifest
--supply-key: Read the manifest’s signing key from stdin or a prompt
--trust-actor <LOGIN>: Treat deliveries from this login as trusted (repeatable)
--hmac-header <H>: Verify an HMAC in header H; the key is read from stdin or a prompt
--hmac-prefix : The prefix before the HMAC in the header, e.g. sha256=
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

–hmac-header reads the HMAC key, and –supply-key the manifest’s signing key, from stdin or a no-echo prompt. Without either, the server mints a secret and it is printed once: in a pipe it is the whole output, on a terminal it comes with the URL and a test call. A manifest hook set again without –supply-key keeps its key.

spool webhook rotate

Mint a new secret for a webhook; the old one stops working

Usage: spool webhook rotate [OPTIONS] <NAME>

spool webhook rotate stripe  # the old secret stops working

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

Mints a new token, or a manifest hook’s new signing key, and prints it once as webhook set does. A hook whose HMAC key its sender chose is set again with the new key instead.

spool webhook delete

Delete a webhook

Usage: spool webhook delete [OPTIONS] <NAME>

spool webhook delete stripe

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool webhook deliveries

A webhook’s recent deliveries

Usage: spool webhook deliveries [OPTIONS] <NAME>

spool webhook deliveries stripe

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool event

The project’s event bus

Usage: spool event [OPTIONS] <COMMAND>

spool event list
spool event emit deploy.done --key web

spool event list

Recent events on the project’s bus

Usage: spool event list [OPTIONS]

spool event list
spool event list --limit 100 -o json

--limit <N>: Rows per page
--cursor <C>: Start from this cursor, from a previous page’s more: hint
--all: Fetch every page
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool event get

One event and its payload

Usage: spool event get [OPTIONS] <ID>

spool event get evt-9aP

<ID>: Its id
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool event emit

Publish an event; inside a job, once per run

Usage: spool event emit [OPTIONS] <TYPE>

spool event emit deploy.done
spool event emit deploy.done --key web --payload '{"version":"1.4.2"}'

<TYPE>: The event type
--key <K>: The event’s subject, which handlers and waits match on
--payload <JSON>: The payload: inline JSON, @file or -
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

Inside a job this is a step of the run: a replay returns the first event’s id and does not emit again. Outside a job it publishes now, every time.

spool event types

The event types this project has seen

Usage: spool event types [OPTIONS]

spool event types

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool repo

Repositories whose pushes and pull requests run

Usage: spool repo [OPTIONS] <COMMAND>

spool repo list
spool repo connect github.com/acme/web --repo-credential gh

spool repo list

Repositories connected to the project

Usage: spool repo list [OPTIONS]

spool repo list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool repo connect

Run a repository’s pipelines on its pushes

Usage: spool repo connect [OPTIONS] <URL|OWNER/NAME>

spool repo connect https://github.com/acme/web --repo-credential gh  # runs .spool/*.yaml on each push
spool repo connect github.com/acme/web --repo-path ci/build.yaml --pull-requests
spool repo connect acme/web --forge-host git.example.com --status-credential forge

<URL|OWNER/NAME>: The repository: a URL or owner/name
--repo-credential <NAME>: Credential to clone it with
--status-credential <NAME>: Credential to post commit statuses with
--repo-path <PATH>: Run this one file instead of every .spool/*.yaml
--pull-requests: Run pull requests too, not only pushes
--forge-host <HOST>: The forge’s host, for a self-hosted one
--webhook <NAME>: The webhook its pushes arrive on
--when <CEL>: Only pushes this CEL expression accepts
--github-app: Connect through the GitHub App, and fail if it can’t be used
--no-github-app: Never use the GitHub App, even where it is installed
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

Without –repo-path, a push runs every .spool/*.yaml at the pushed commit, each as its own run; with it, that one file. owner/name alone needs –forge-host. When this makes the forge’s webhook, its secret is printed once: alone in a pipe, with where to paste it on a terminal. Connecting again changes what it builds and keeps the webhook.

spool repo disconnect

Stop running a repository’s pipelines

Usage: spool repo disconnect [OPTIONS] <REPO>

spool repo disconnect acme/web
spool repo disconnect acme-web --yes  # by its id

<REPO>: owner/name, or the id from spool repo list
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool state

Durable state cells

Usage: spool state [OPTIONS] <COMMAND>

spool state get deployed  # in a job
spool state list --run run-7Hk2  # another run's cells

spool state get

A cell’s value; empty when unset

Usage: spool state get [OPTIONS] <KEY>

spool state get deployed  # in a job; empty when unset
spool state get deployed --required  # exit 4 when unset
spool state get counter --entity web
spool state get deployed --run run-7Hk2  # from a terminal

<KEY>: The cell
--required: Exit 4 when the cell is unset
--run <RUN>: Another run’s cells
--entity <NAME>: An entity’s cells, shared across runs
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

Prints the value itself. An unset cell prints nothing and exits 0; –required makes it exit 4.

spool state list

Every cell, with its value and version

Usage: spool state list [OPTIONS]

spool state list  # in a job
spool state list --entity web -o json

--run <RUN>: Another run’s cells
--entity <NAME>: An entity’s cells, shared across runs
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool state version

A cell’s version, for state cas --expect; empty when unset

Usage: spool state version [OPTIONS] <KEY>

spool state version counter

<KEY>: The cell
--run <RUN>: Another run’s cells
--entity <NAME>: An entity’s cells, shared across runs
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool state set

Set a cell (in a job)

Usage: spool state set [OPTIONS] <KEY> <VALUE>

spool state set deployed web-2
spool state set offset -5  # values may start with -
echo big | spool state set notes -

<KEY>: The cell
<VALUE>: The value; - reads stdin
--entity <NAME>: An entity’s cells, shared across runs
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool state add

Claim a cell nothing holds yet; exit 3 if it is held (in a job)

Usage: spool state add [OPTIONS] <KEY> [VALUE]

spool state add lock:web  # exit 3 if it is held

<KEY>: The cell
<VALUE>: The value (default true); - reads stdin
--entity <NAME>: An entity’s cells, shared across runs
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool state cas

Set a cell if its version is still N; exit 3 if not (in a job)

Usage: spool state cas [OPTIONS] --expect <N> <KEY> <VALUE>

spool state cas counter 5 --expect "$(spool state version counter)"

<KEY>: The cell
<VALUE>: The new value; - reads stdin
--expect <N>: The version the cell must still be at; spool state add sets an unset one
--op <NAME>: Name this swap, so a replay returns its first result
--entity <NAME>: An entity’s cells, shared across runs
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool state incr

Add to a number cell and print the new value (in a job)

Usage: spool state incr [OPTIONS] <KEY> [BY]

spool state incr builds
spool state incr budget -3 --op spend

<KEY>: The cell
<BY>: How much to add (default 1; may be negative)
--op <NAME>: Name this increment, so a replay returns its first result
--entity <NAME>: An entity’s cells, shared across runs
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool state delete

Remove a cell (in a job)

Usage: spool state delete [OPTIONS] <KEY>

spool state delete deployed

<KEY>: The cell
--entity <NAME>: An entity’s cells, shared across runs
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool artifact

Run artifacts and the project cache

Usage: spool artifact [OPTIONS] <COMMAND>

spool artifact put dist/app.tar.gz  # in a job
spool artifact list --run run-7Hk2

spool artifact put

Save a file or directory as an artifact (in a job)

Usage: spool artifact put [OPTIONS] <PATH>

spool artifact put dist/app.tar.gz
spool artifact put target --cache cargo-$HASH  # a directory, into the project cache

<PATH>: The file or directory
--name <N>: Save it under this name (default the file’s name)
--cache <KEY>: Save it to the project cache under KEY instead of the run
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool artifact get

Fetch an artifact

Usage: spool artifact get [OPTIONS] <NAME> [PATH]

spool artifact get app.tar.gz  # in a job
spool artifact get target ./target --cache cargo-$HASH --fallback-prefix cargo-
spool artifact get app.tar.gz --run run-7Hk2  # from a terminal

<NAME>: The artifact’s name
<PATH>: Where to write it (default its name)
--run <RUN>: Another run’s artifact
--cache <KEY>: From the project cache, under KEY
--fallback-prefix : On a cache miss, the newest key starting with P (in a job)
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool artifact list

A run’s artifacts, or the project cache’s

Usage: spool artifact list [OPTIONS]

spool artifact list  # in a job
spool artifact list --cache-prefix cargo-

--run <RUN>: Another run’s artifacts
--cache <KEY>: The project cache’s artifacts under KEY
--cache-prefix : The project cache’s keys starting with P
--limit <N>: Rows per page
--cursor <C>: Start from this cursor, from a previous page’s more: hint
--all: Fetch every page
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool artifact delete

Delete an artifact

Usage: spool artifact delete [OPTIONS] <--run <RUN>|--cache <KEY>> <NAME>

spool artifact delete target --cache cargo-old

<NAME>: The artifact’s name
--run <RUN>: A run’s artifact
--cache <KEY>: From the project cache, under KEY
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool node

The node kinds a graph can use

Usage: spool node [OPTIONS] <COMMAND>

spool node list
spool node get http

spool node list

The node kinds a graph can use

Usage: spool node list [OPTIONS]

spool node list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool node get

One node kind: its config, inputs and outputs

Usage: spool node get [OPTIONS] <KIND>

spool node get http

<KIND>: The node kind
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool connector

Connectors and connector packages

Usage: spool connector [OPTIONS] <COMMAND>

spool connector list
spool connector get github

spool connector list

Built-in connectors and installed packages

Usage: spool connector list [OPTIONS]

spool connector list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool connector get

One connector and its actions

Usage: spool connector get [OPTIONS] <NAME>

spool connector get github

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool connector add

Install a connector package from git; again with a new ref upgrades

Usage: spool connector add [OPTIONS] <GIT-URL@REF>

spool connector add https://github.com/acme/spool-jira@v1.2.0

<GIT-URL@REF>: The package: its git URL and a ref
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool connector delete

Remove an installed connector package

Usage: spool connector delete [OPTIONS] <NAME>

spool connector delete jira

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool agent

Agents and agent tokens; run your own

Usage: spool agent [OPTIONS] <COMMAND>

spool agent list
spool agent token create --pool builders --cap shell --scope acme/web

spool agent list

Agents registered with the server

Usage: spool agent list [OPTIONS]

spool agent list
spool agent list --pool builders --include-finished

--pool <NAME>: Only agents in this pool
--include-finished: Include agents that have exited
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool agent get

One agent

Usage: spool agent get [OPTIONS] <AGENT-ID>

spool agent get agt-3xR

<AGENT-ID>: The agent
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool agent shutdown

Ask an agent to finish what it runs and exit

Usage: spool agent shutdown [OPTIONS] <AGENT-ID>

spool agent shutdown agt-3xR

<AGENT-ID>: The agent
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool agent delete

Forget an agent and revoke its token

Usage: spool agent delete [OPTIONS] <AGENT-ID>

spool agent delete agt-3xR

<AGENT-ID>: The agent
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool agent token

Agent tokens

Usage: spool agent token [OPTIONS] <COMMAND>

spool agent token list --scope acme

spool agent token list

Agent tokens for a scope, or the deployment’s

Usage: spool agent token list [OPTIONS]

spool agent token list --scope acme/web

--scope <ORG[/PROJECT]>: Tokens for this org or project (default the context’s org)
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool agent token create

Mint an agent token; printed once

Usage: spool agent token create [OPTIONS] --cap <CAP> <AGENT-ID|--pool <NAME>>
       --scope <ORG[/PROJECT]>

spool agent token create --pool builders --cap shell --cap docker --scope acme/web
spool agent token create agt-3xR --cap gpu --scope acme --expires-in 30d

<AGENT-ID>: The agent the token is for
--pool <NAME>: A pool of agents the token is for
--cap <CAP>: A capability the agent provides (repeatable)
--scope <ORG[/PROJECT]>: Claim work in this org or project
--name <LABEL>: A label for the token
--expires-in <DUR>: Expire after DUR
--tier <TIER>: Which runs the agent may take
--max-claims <N>: Stop after N claims
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool agent token delete

Revoke an agent token

Usage: spool agent token delete [OPTIONS] <TOKEN-ID>

spool agent token delete atk-5mN

<TOKEN-ID>: The token
--scope <ORG[/PROJECT]>: The org or project the token is for (default the context’s org)
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool agent run

Run an agent here, claiming work from a server

Usage: spool agent run [OPTIONS] [SERVER-URL] [AGENT-ID]

spool agent run https://hyperspool.dev  # reads HYPERSPOOL_AGENT_TOKEN
spool agent run https://hyperspool.dev laptop --cap shell --cap docker

<SERVER-URL>: The server to claim from
<AGENT-ID>: This agent’s id
--cap <CAP>: A capability this agent provides (repeatable)
--side-log <PATH>: Also write the agent’s log to PATH
--token-file <PATH>: Read the token from PATH and delete the file (-: stdin)
--step-user <USER>: Run jobs as USER, not as the agent (Linux, agent runs as root)

spool agent dispatch

Start a command whenever a server has work for these capabilities

Usage: spool agent dispatch [OPTIONS] --provides <CAP> <SERVER-URL> -- <CMD>...

spool agent dispatch https://hyperspool.dev --provides gpu -- ./start-gpu-box.sh
spool agent dispatch https://hyperspool.dev --provides shell --interval 30s --once -- kubectl create -f job.yaml

<SERVER-URL>: The server to watch for work
--provides <CAP>: A capability the command’s agents provide (repeatable)
--together <CAP,CAP>: Capabilities the command builds as one shape: work needing any of them gets an environment with all of them (comma-separated)
--interval <DUR>: The longest to go between looks for work
--once: Ask once, start what is needed, and exit
<CMD>: The command to start

spool secret

Write-only values a run can read

Usage: spool secret [OPTIONS] <COMMAND>

spool secret list
printf %s "$TOKEN" | spool secret set deploy-token

spool secret list

The project’s secrets, without their values

Usage: spool secret list [OPTIONS]

spool secret list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool secret get

One secret’s metadata; its value is never shown

Usage: spool secret get [OPTIONS] <NAME>

spool secret get deploy-token  # metadata; never the value

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool secret set

Set a secret; the value comes from stdin or a prompt

Usage: spool secret set [OPTIONS] <NAME>

spool secret set deploy-token  # prompts without echo
printf %s "$TOKEN" | spool secret set deploy-token
spool secret set tls-key < key.pem

<NAME>: The secret’s name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

The value is read from stdin, or prompted for without echo on a terminal. It is never a flag, so it cannot land in shell history. An empty value is refused.

spool secret delete

Delete a secret

Usage: spool secret delete [OPTIONS] <NAME>

spool secret delete deploy-token

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool credential

Typed credentials for http and connector steps

Usage: spool credential [OPTIONS] <COMMAND>

spool credential list
gh auth token | spool credential set gh --kind bearer

spool credential list

The project’s credentials, without their secrets

Usage: spool credential list [OPTIONS]

spool credential list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool credential get

One credential’s metadata

Usage: spool credential get [OPTIONS] <NAME>

spool credential get gh

<NAME>: Its name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool credential set

Set a credential that http and connector steps reference by name

Usage: spool credential set [OPTIONS] --kind <KIND> <NAME>

gh auth token | spool credential set gh --kind bearer
spool credential set registry --kind basic --username ci  # prompts
spool credential set openai --kind api-key --header Authorization < key.txt

<NAME>: What steps write as credential: <NAME>
--kind <KIND>: bearer, api-key, basic or url-token
--header <H>: The header an api-key goes in (api-key)
--username : The user name (basic)
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

The secret part (the token, the api-key value, or the password) is read from stdin, or prompted for without echo on the terminal. It is never a flag, so it cannot land in shell history. An empty value is refused.

spool credential delete

Delete a credential

Usage: spool credential delete [OPTIONS] <NAME>

spool credential delete gh

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool account

Connected accounts on other services

Usage: spool account [OPTIONS] <COMMAND>

spool account list
spool account connect gmail --provider google

spool account list

Accounts on other services the project has connected

Usage: spool account list [OPTIONS]

spool account list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool account connect

Connect an account: opens the console page that asks the provider

Usage: spool account connect [OPTIONS] --provider <P> <NAME>

spool account connect gmail --provider google
spool account connect gmail --provider google --print

<NAME>: What steps call the account
--provider : The service to connect
--print: Print the console URL instead of opening it
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool account delete

Disconnect an account

Usage: spool account delete [OPTIONS] <NAME>

spool account delete gmail

<NAME>: Its name
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool token

Your personal access tokens

Usage: spool token [OPTIONS] <COMMAND>

spool token list
spool token create laptop --expires-in 90d

spool token list

Your personal access tokens

Usage: spool token list [OPTIONS]

spool token list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool token create

Mint a personal access token; printed once

Usage: spool token create [OPTIONS] <NAME>

spool token create ci --expires-in 90d  # printed once

<NAME>: A label for the token
--expires-in <DUR>: Expire after DUR
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool token delete

Revoke a personal access token

Usage: spool token delete [OPTIONS] <TOKEN-ID>

spool token delete tok-8wE

<TOKEN-ID>: The token
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool terms

The terms of service, and accepting them

Usage: spool terms [OPTIONS] <COMMAND>

spool terms show
spool terms accept

spool terms show

The version in force and the one you accepted

Usage: spool terms show [OPTIONS]

spool terms show  # the version in force and the one you accepted

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool terms accept

Accept the terms of service and privacy notice in force

Usage: spool terms accept [OPTIONS]

spool terms accept  # shows the links and asks first
spool terms accept --yes  # from a script

-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool org

Orgs, members, usage

Usage: spool org [OPTIONS] <COMMAND>

spool org list
spool org member list

spool org list

The orgs you belong to

Usage: spool org list [OPTIONS]

spool org list

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool org create

Create an org, with you as its owner

Usage: spool org create [OPTIONS] <SLUG>

spool org create acme --name 'Acme Inc'

<SLUG>: The org’s slug
--name <N>: Its display name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool org use

Make an org current in this context

Usage: spool org use [OPTIONS] <SLUG>

spool org use acme  # in the current context

<SLUG>: The org’s slug
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool org usage

What an org has used against its plan

Usage: spool org usage [OPTIONS]

spool org usage
spool org usage --since 7d --org acme

--since <DUR>: Usage since DUR ago or an RFC 3339 time (default this period)
--org <SLUG>: The org, for this command
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool org export

Write an org’s data to a JSON file

Usage: spool org export [OPTIONS] <SLUG>

spool org export acme  # to acme-export.json
spool org export acme --file /tmp/acme.json

<SLUG>: The org’s slug
--file <FILE>: Where to write it (default SLUG-export.json)
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

The file holds the org’s members, projects, every workflow version, schedules, handlers, webhooks, the names of secrets and credentials, and each run with its history. Secret values, logs and artifacts are not in it: each run names the paths that serve its log and artifacts.

spool org delete

Delete an org and everything in it

Usage: spool org delete [OPTIONS] <SLUG>

spool org delete acme  # asks first
spool org delete acme --yes

<SLUG>: The org’s slug
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

Members lose access at once and the rest is removed in the background: runs are cancelled, then projects, runs, logs, artifacts, schedules, webhooks and secrets go. A paid subscription ends first. The slug stays taken for 30 days. Needs the owner role.

spool org member

An org’s members

Usage: spool org member [OPTIONS] <COMMAND>

spool org member list

spool org member list

The org’s members and their roles

Usage: spool org member list [OPTIONS]

spool org member list --org acme

--org <SLUG>: The org, for this command
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool org member set

Add a member, or change a member’s role

Usage: spool org member set [OPTIONS] --role <ROLE> <EMAIL>

spool org member set ana@acme.dev --role admin

<EMAIL>: The member’s email
--role <ROLE>: viewer, member, admin or owner
--org <SLUG>: The org, for this command
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool org member delete

Remove a member from the org

Usage: spool org member delete [OPTIONS] <EMAIL>

spool org member delete ana@acme.dev

<EMAIL>: The member’s email
-y, --yes: Don’t ask; needed when there is no terminal to ask on
--org <SLUG>: The org, for this command
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool org billing

An org’s billing

Usage: spool org billing [OPTIONS] <COMMAND>

spool org billing retry

spool org billing retry

Try a declined charge for added seats again now

Usage: spool org billing retry [OPTIONS]

spool org billing retry --org acme  # after fixing the card

--org <SLUG>: The org, for this command
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool project

Projects, members, limits

Usage: spool project [OPTIONS] <COMMAND>

spool project list
spool project use acme/web

spool project list

The org’s projects

Usage: spool project list [OPTIONS]

spool project list
spool project list --org acme

--org <SLUG>: The org, for this command
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool project create

Create a project in the org

Usage: spool project create [OPTIONS] <SLUG>

spool project create api --name 'Public API'

<SLUG>: The project’s slug
--name <N>: Its display name
--org <SLUG>: The org, for this command
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool project use

Make a project current in this context

Usage: spool project use [OPTIONS] <[ORG/]SLUG>

spool project use web
spool project use acme/web

<[ORG/]SLUG>: The project: slug, or org/slug
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool project storage

What the project stores, against its limits

Usage: spool project storage [OPTIONS]

spool project storage

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool project update

Change a project’s limits

Usage: spool project update [OPTIONS]

spool project update --run-cap 20
spool project update --run-cap unlimited

--run-cap <N|unlimited>: Most runs at once: a number or unlimited
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool project delete

Delete a project and everything in it

Usage: spool project delete [OPTIONS] <SLUG>

spool project delete old-api --org acme

<SLUG>: The project’s slug
-y, --yes: Don’t ask; needed when there is no terminal to ask on
--org <SLUG>: The org, for this command
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context

spool project member

A project’s members

Usage: spool project member [OPTIONS] <COMMAND>

spool project member list

spool project member list

The project’s members and their roles

Usage: spool project member list [OPTIONS]

spool project member list --project acme/web

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool project member set

Add a member, or change a member’s role

Usage: spool project member set [OPTIONS] --role <ROLE> <EMAIL>

spool project member set sam@acme.dev --role viewer

<EMAIL>: The member’s email
--role <ROLE>: viewer, member or admin
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool project member delete

Remove a member from the project

Usage: spool project member delete [OPTIONS] <EMAIL>

spool project member delete sam@acme.dev

<EMAIL>: The member’s email
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too
-c, --context <NAME>: Use this context for this command
--server <URL>: Talk to this server, without a context
--org <SLUG>: The org, for this command
--project <[ORG/]SLUG>: The project, for this command

spool context

The servers you use, and which is current

Usage: spool context [OPTIONS] <COMMAND>

spool context list
spool context use acme-web

spool context list

Your contexts, and running spool dev servers

Usage: spool context list [OPTIONS]

spool context list
spool context list -o json

-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

Contexts from the config file, and each running spool dev (source dev). A context in the config wins over a dev server of the same name.

spool context get

A context: its server, login and scope (default the current one)

Usage: spool context get [OPTIONS] [NAME]

spool context get  # what commands use now, and why
spool context get acme-web --verify  # ask the server who the token is

<NAME>: The context (default the one commands use now)
--verify: Ask the server who the token belongs to
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

With no name, shows the context commands use now: –server, -c, HYPERSPOOL_SERVER, SPOOL_CONTEXT, then the current context, first match wins. Tokens are shown as a preview only.

spool context use

Make a context current

Usage: spool context use [OPTIONS] <NAME>

spool context use acme-web
spool context use local  # a running spool dev

<NAME>: The context
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool context add

Add a context: a login plus an org and project

Usage: spool context add [OPTIONS] --login <LOGIN> --scope <ORG/PROJECT> <NAME>

spool context add acme-api --login hyperspool.dev --scope acme/api

<NAME>: The new context’s name
--login <LOGIN>: The login it uses, from spool login
--scope <ORG/PROJECT>: Its org and project
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool context update

Change a context’s login or scope

Usage: spool context update [OPTIONS] <NAME>

spool context update acme-web --scope acme/web-next

<NAME>: The context
--login <LOGIN>: Use this login instead
--scope <ORG/PROJECT>: Use this org and project instead
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool context rename

Rename a context

Usage: spool context rename [OPTIONS] <OLD> <NEW>

spool context rename hyperspool.dev acme-web

<OLD>: Its name now
<NEW>: Its new name
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool context delete

Delete a context; its login stays

Usage: spool context delete [OPTIONS] <NAME>

spool context delete old --yes

<NAME>: The context
-y, --yes: Don’t ask; needed when there is no terminal to ask on
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool step

Run a command once per run (in a job)

Usage: spool step [OPTIONS] <NAME> -- <COMMAND>...

spool step build -- make
spool step "test-$shard" --label "tests $shard" -- make test SHARD=$shard

<NAME>: The step’s name. Reusing it, in a loop say, is fine: each use is recorded separately
--label <TEXT>: What this pass shows as, when it differs from NAME
<COMMAND>: The command

Recorded: a replay returns the first result and does not run the command again. Exits with the command’s own code; 125 when it could not be started, 126 when it is not executable, 127 when it does not exist.

spool lock

Run a command holding a named lease (in a job)

Usage: spool lock [OPTIONS] <GROUP> [-- <COMMAND>...]

spool lock deploy-prod -- ./deploy.sh  # one run at a time
spool lock deploy-prod  # exit 0 once it is held

<GROUP>: The lease’s group
<COMMAND>: The command to run holding it; left out, exit once it is held

spool sleep

Suspend for a duration, releasing the agent (in a job)

Usage: spool sleep [OPTIONS] <DURATION>

spool sleep 30m
spool sleep 2h

<DURATION>: How long: 500ms, 30s, 5m, 2h, 7d

spool wait

Suspend until a signal or an event arrives (in a job)

Usage: spool wait [OPTIONS] <COMMAND>

spool wait signal deploy-approved

spool wait signal

Suspend until a signal arrives, and print its payload

Usage: spool wait signal [OPTIONS] <NAME>

spool wait signal deploy-approved  # prints the payload
spool wait signal deploy-approved --timeout 24h  # exit 124 if none comes

<NAME>: The signal’s name
--timeout <DUR>: Stop waiting after DUR and exit 124
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool wait event

Suspend until an event arrives, and print it

Usage: spool wait event [OPTIONS] <TYPE>

spool wait event deploy.done --timeout 1h  # prints the event
spool wait event pr.comment --accept-untrusted  # a fork's comment ends it too

<TYPE>: The event type
--accept-untrusted: Let an untrusted event end it, such as a fork’s pull request
--timeout <DUR>: Stop waiting after DUR and exit 124
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool spawn

Start a child run and print its id (in a job)

Usage: spool spawn [OPTIONS] <FILE|--workflow <NAME[@V]>|--node <KIND>>

spool spawn child.yaml --tag parent  # prints the child's id
spool spawn -w notify --input '{"to":"ops"}'

<FILE>: A pipeline, graph or script; - reads stdin
-w, --workflow <NAME[@V]>: A stored workflow; published unless @V
--node <KIND>: One node kind
--as <KIND>: pipeline, graph or script (read from the file when left out)
--input <JSON>: The child’s input: inline JSON, @file or -
--tag <TAG>: Tag the child (repeatable)
--config <JSON>: Node config (with –node)
--nodes <JSON>: Upstream outputs for a lifted node (with –node)
--origin-repo <R>: The repository the document is from
--origin-path : Its path in the repository
--origin-sha <S>: The commit
--origin-ref <R>: The branch or tag
--origin-forge-host <H>: The forge’s host, for a self-hosted one
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool call

Run a child and print its output when it ends (in a job)

Usage: spool call [OPTIONS] <FILE|--workflow <NAME[@V]>|--node <KIND>>

out=$(spool call -w lint --input @changes.json)
spool call --node http --config @req.json --timeout 5m
spool call child.py -o id  # the child's id

<FILE>: A pipeline, graph or script; - reads stdin
-w, --workflow <NAME[@V]>: A stored workflow; published unless @V
--node <KIND>: One node kind
--as <KIND>: pipeline, graph or script (read from the file when left out)
--input <JSON>: The child’s input: inline JSON, @file or -
--tag <TAG>: Tag the child (repeatable)
--config <JSON>: Node config (with –node)
--nodes <JSON>: Upstream outputs for a lifted node (with –node)
--origin-repo <R>: The repository the document is from
--origin-path : Its path in the repository
--origin-sha <S>: The commit
--origin-ref <R>: The branch or tag
--origin-forge-host <H>: The forge’s host, for a self-hosted one
--timeout <DUR>: Stop waiting after DUR and exit 124
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

Prints the child’s output as JSON; -o id prints its id. With –timeout, exits 124 when it elapses and the child keeps running.

spool checkout

Clone the run’s repository at its commit (in a job)

Usage: spool checkout [OPTIONS] [DIR]

spool checkout  # into ., which must be empty
spool checkout src --depth 1

<DIR>: Where to clone (default ., which must be empty)
--depth <N>: Fetch only the last N commits
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too

spool output

This step’s output for later steps (in a job)

Usage: spool output [OPTIONS] <COMMAND>

spool output set version=1.4.2

spool output set

Set this step’s output for later steps

Usage: spool output set [OPTIONS] <KEY=VALUE|KEY:=JSON|--values <JSON>>

spool output set version=1.4.2 ok:=true
spool output set --values @outputs.json

<KEY=VALUE|KEY:=JSON>: KEY=VALUE for a string, KEY:=JSON for any value
--values <JSON>: Every value at once, as a JSON object: inline, @file or -

spool annotate

Post a note to the run’s page (in a job)

Usage: spool annotate [OPTIONS] [MESSAGE]

spool annotate --name coverage --style info "coverage: 91%"
spool annotate --name coverage --append "- web: 94%"
spool annotate < report.md

<MESSAGE>: The note, in markdown; left out, read from stdin
--name <N>: Name it, so a later annotate with the name replaces it
--style <STYLE>: info, success, warn or error
--title <T>: A title above the note
--append: Add to the named note instead of replacing it

spool activity

Fan work out to agents: run, submit, wait (in a job)

Usage: spool activity [OPTIONS] <COMMAND>

spool activity run build --requires docker -- make image

spool activity run

Run a command on an agent that has the capabilities, and wait

Usage: spool activity run [OPTIONS] <NAME> -- <COMMAND>...

spool activity run build --requires docker -- make image
spool activity run flaky --attempts 3 --backoff 10s --retry-on-exit 75 -- ./check.sh

<NAME>: The activity’s name. Reusing it, in a loop say, is fine: each use is recorded separately
--requires <CAP>: A capability the agent must have (repeatable)
--agent <ID>: Run it on this agent
--attempts <N>: Try up to N times
--backoff <DUR>: Wait DUR between attempts
--retry-on-exit <CODE>: Retry only on this exit code (repeatable)
<COMMAND>: The command

spool activity submit

Start a command on an agent; activity wait collects it

Usage: spool activity submit [OPTIONS] <NAME> -- <COMMAND>...

spool activity submit shard-1 --requires gpu -- ./train.sh 1

<NAME>: The activity’s name. Reusing it, in a loop say, is fine: each use is recorded separately
--requires <CAP>: A capability the agent must have (repeatable)
--agent <ID>: Run it on this agent
--attempts <N>: Try up to N times
--backoff <DUR>: Wait DUR between attempts
--retry-on-exit <CODE>: Retry only on this exit code (repeatable)
<COMMAND>: The command

spool activity wait

Wait for submitted activities; exit with the first failure’s code, or 1 with –all

Usage: spool activity wait [OPTIONS] <NAME|--all>

spool activity wait shard-1 shard-2  # exit with the first failure's code
spool activity wait --all  # exit 1 if any failed

<NAME>: The activities, in order
--all: Every activity this run submitted
-o, --output <FORMAT>: table, json, yaml or id
--headers: Print the table header in a pipe too