Developer CLI

Create Actions, wait for typed human decisions, manage Watches, and wrap scheduled jobs with the ActionBox CLI.

The actionbox CLI lets scripts, CI jobs, scheduled tasks, and agents ask a human for a decision and continue when the answer arrives.

Install

The CLI is publicly available from PyPI as platform-specific wheels for macOS, Linux, and Windows on AMD64 and ARM64. Python 3.9 or newer is required to install the wheel; the ActionBox command itself is a prebuilt binary and does not require Go.

python -m pip install actionbox
actionbox version

Standalone installer status

The install.sh, PowerShell, Homebrew, and direct-download paths are not public installation options yet because their release archives are not on the ActionBox download host. Use the PyPI command above until those paths are announced here.

Create a Source in the ActionBox dashboard, then configure and verify the CLI:

actionbox configure
actionbox doctor

Interactive token entry is hidden. For CI or another non-interactive runner, pipe the Source token through standard input so it does not appear in the process arguments:

printf '%s\n' "$ACTIONBOX_API_KEY" | actionbox configure --token-stdin
actionbox doctor

ACTIONBOX_CONFIG_FILE selects an isolated configuration file when a runner should not use the default user-level path. The defaults are:

macOS: ~/Library/Application Support/actionbox/config.json
Linux: ${XDG_CONFIG_HOME:-$HOME/.config}/actionbox/config.json
Windows: %AppData%\actionbox\config.json

On Unix-like systems, the CLI writes the directory for the current user and the file with 0600 permissions. It rejects symbolic-link and group- or world-readable configuration files.

Ask and wait

actionbox ask "Deploy to production?" \
  --option approve="Approve deployment" \
  --option reject="Reject deployment" \
  --wait \
  --timeout 30m \
  --json

ask requires at least one --option or an --interaction-json object. Use id=Label to keep option IDs stable.

Important options include:

Option	Purpose
`--description TEXT`	Add review context.
`--priority LEVEL`	`low`, `normal`, `high`, or `urgent`.
`--option VALUE`	Repeat up to three times; accepts `id=Label`.
`--interaction-json JSON	@FILE`
`--context-json JSON	@FILE`
`--on-expire-json JSON	@FILE`
`--callback-url URL`	Send terminal state to a public HTTPS callback.
`--dedupe-key KEY`	Merge repeated open occurrences.
`--expires RFC3339`	Set server-side expiration.
`--no-origin`	Do not attach automatically detected CI origin metadata.
`--wait`	Wait until terminal state or local timeout.
`--timeout DURATION`	Maximum local wait; defaults to one hour.
`--json`	Print the structured result.
`--quiet`	Print only the selected option while waiting.

A terminal Action prints a descriptive result and returns normally; add --quiet for only the selected option. A local wait timeout exits 124 and leaves the Action open; Ctrl+C exits 130 and also leaves it open. API, network, or validation errors exit 1.

CI origin metadata

In recognized GitHub Actions, GitLab CI, Jenkins, and CircleCI environments, the CLI automatically adds bounded origin metadata to the Action. Depending on the provider, this can include a workflow or job reference, repository and branch labels, a shortened commit identifier, and a build URL. This makes the request easier for a reviewer to verify, but private repository names and CI URLs may be sensitive. Add --no-origin to send or ask when that context should not leave the runner.

Branch on the decision value

Do not interpret every successful process exit as approval. Read the selected option or parse the JSON decision or typed response field.

Other commands

actionbox send TITLE
actionbox get ACTION_ID
actionbox resolve ACTION_ID
actionbox cancel ACTION_ID
actionbox watch create|list|pause|resume|rotate-token|archive
ACTIONBOX_WATCH_URL=URL actionbox run -- COMMAND
actionbox mcp

--watch-url URL remains available, but the environment variable avoids placing the bearer capability in shell history or the Actionbox process arguments. Run actionbox COMMAND --help for the exact options shipped with your installed version. Keep Source tokens and Watch capability URLs out of logs, browser code, and source control.

Update or uninstall

python -m pip install --upgrade actionbox
python -m pip uninstall actionbox

Uninstalling the package does not remove the saved Source token or revoke the Source. Revoke or rotate the Source from the dashboard when the machine or integration should no longer be trusted.