composer-cli — User Guide

composer-cli is a command-line tool for controlling a running Vindral Composer Runtime over its HTTP Runtime API. It runs on Windows and Linux, issues one command per invocation (so it scripts cleanly), and authenticates with the Runtime's existing API-key mechanism.

The Runtime API is only served by the headless Composer Runtime, not Composer Desktop, and requires the Runtime to be started with --runtime-api-port (e.g. 9101).

Installation

Copy the published composer-cli binary somewhere on your PATH:

• Windows: composer-cli.exe
• Linux: composer-cli (chmod +x composer-cli)

Quick start

# Talk to a Runtime on this machine (default http://localhost:9101)
composer-cli status

# Talk to a specific instance
composer-cli status --url http://encoder1.example.com:9101

# Load a project, start it, check it, stop it
composer-cli load MorningShow.prj
composer-cli status
composer-cli stop

Choosing which Runtime to talk to

Resolution order (highest priority first):

1. --url http://host:port
2. --host <host> --port <port>
3. --context <name> (a saved alias — see below)
4. the default context
5. http://localhost:9101

Named contexts (instance aliases)

If you manage several Runtimes, save them as named contexts (the kubectl / aws --profile model) so you don't retype URLs and keys:

composer-cli context-add dc1-enc2 --url https://enc2.dc1.example.com:9101 --apikey <KEY>
composer-cli context-add dc2-enc1 --url https://enc1.dc2.example.com:9101 --apikey <KEY>

composer-cli context-list                 # show all; the default is marked with *
composer-cli context-use dc1-enc2         # set the default

composer-cli status                       # uses the default context
composer-cli status --context dc2-enc1    # one-off override

Contexts are stored in:

• Windows: %APPDATA%\composer-cli\config.json
• Linux: ~/.config/composer-cli/config.json (created chmod 600)

Authentication

The Runtime validates an apikey against its apikeys.json. If that file is empty, the API is open and no key is needed. Otherwise provide a key (sent as the apikey HTTP header, never in the URL):

Key resolution order:

1. --apikey <KEY>
2. COMPOSER_API_KEY environment variable
3. the selected context's stored key

If you target a non-loopback host without a key, the tool prints a warning to stderr before proceeding.

Commands

Status & inventory

Health probes

Check the Runtime's container/orchestrator health probes. These are served by a separate, unauthenticated listener on the Runtime's health port — so pass --health-port (or set COMPOSER_HEALTH_PORT); it must match the port the Runtime was started with (--health-port). The host comes from normal target resolution (--url / --host / --context); only the port is swapped to the health port.

composer-cli health --host enc1 --health-port 8088               # readiness (default)
composer-cli health --host enc1 --probe startup --health-port 8088
COMPOSER_HEALTH_PORT=8088 composer-cli health --host enc1 --probe live

Probes: startup (boot complete) → /startup, live (main loop ticking) → /health, ready (startup done and Idle/Running) → /ready. Use it in scripts the same way as status:

if composer-cli health --host enc1 --health-port 8088 >/dev/null; then echo "ready"; fi

Lifecycle

Project files

Contexts (local config only — no network)

Global options

Output, scripting & exit codes

• Command results go to stdout; warnings/errors go to stderr — so you can pipe stdout safely. Use --json to get machine-readable output.
• Exit codes:

Note: a mistyped or unknown verb exits 1 (the parser rejects it before any verb runs), while a recognized verb given a bad argument exits 2.

Example:

if composer-cli status --context dc1-enc2 >/dev/null; then
  echo "encoder is up"
fi

Logging

The CLI keeps its own dated log (separate from the Runtime's logs) recording each invocation — target, HTTP status, outcome, and duration. API keys are redacted. Default location:

• Windows: %LOCALAPPDATA%\composer-cli\logs\
• Linux: ~/.local/share/composer-cli/logs/

Override with --logpath. Add -v for live request/response detail on the console.

Troubleshooting