CLI overview

jstm manages agents, workspaces, organizations, vaults, connections, catalogs, triggers, and runs from your terminal. It is a pure HTTP client for the JoyStream backend.

jstm --help
jstm commands       # print the entire command tree
jstm --version      # or -V

jstm and joystream are the same program. The prebuilt binary is named joystream; jstm is the short alias. These docs use jstm.

Global flags

Flag	Purpose
`--version`, `-V`	Print the CLI version and exit
`--install-completion`	Install shell completion for your shell
`--show-completion`	Print the completion script instead of installing it
`--help`	Show help for the app, a group, or a command

Running jstm with no arguments prints help rather than doing anything.

JSON output

--json is a per-command flag, not a global one. Nearly every command that reads or writes data supports it.

jstm agent list --json
jstm workspace context --json

A few commands have no --json because their output is interactive or a single line: connection test, connection add, connection remove, triggers delete, triggers webhook-url, org invite, org remove, profile emails subcommands, and jstm commands. jstm ticket list and jstm ticket show also accept --out <file> to write the payload to a file.

stdout and stderr are separate

Results go to stdout. Errors, panels, prompts, and log records go to stderr. This means --json output on stdout is always a clean, pipeable stream:

jstm agent list --json | jq '.[] | .handle'

Typed error contracts are the deliberate exception. In --json mode, errors like credential_required print as pure JSON on stdout so a consumer can parse and branch on them, rather than as a formatted panel.

Exit codes

Code	Meaning
`0`	Success
`1`	Failure — an API error, a validation failure, or a declined confirmation
`2`	Usage error — an unknown flag, a missing argument, or an invalid command form

Three commands carry extra meaning in their exit code:

jstm agent conform exits with the conformance report’s own code. 2 here means the package couldn’t be read or a flag value was invalid.
jstm agent readiness exits non-zero whenever there are blockers, so it works directly as a gate in a script.
A bare jstm agent plan is a usage error and exits 2. Creation must be explicit — pass --new or a session id.

Error messages

The CLI distinguishes between failure modes rather than dumping status codes.

Situation	What you see
Backend unreachable	A connection error naming the API URL it tried, and how to change it
`401`	”Session expired” and instructions to run `jstm login`
`403`	The status and detail. This is a permissions problem, not a login problem, and is deliberately not treated as one
Anything else	The status and the response detail

Set JOYSTREAM_DEBUG=1 to log the full traceback to stderr.

Command groups

Group	What it does
Authentication	`init`, `login`, `logout`, `whoami`
`agent`	Plan, build, conform, promote, run, inspect, manage, and schedule agents
`ticket`	Read a run’s work as tickets
`workspace`	Create, list, switch workspaces and manage members
`org`	Organizations, members, invitations
`profile`	Username and email management
`vault`	Vaults, credentials, audit, and scope
`connection`	Service connections
`mcp`	MCP server catalog, endpoints, and repositories
`skills`	Skills catalog and source repositories
`registry`	The resolved catalog, with tier precedence
`session`	Pin skills to a builder session
`triggers`	Trigger bindings, webhooks, and events
`input-requests`	Answer an agent that’s waiting on input
`credits`	Balance and ledger
`admin`	User administration for self-hosted operators

jstm commands always reflects the version you have installed.

Configuration

Config paths, environment variables, and precedence.

Addressing

Handles, UUIDs, FQNs, and run addresses.

Using the CLI

Commands

Global flags

JSON output

stdout and stderr are separate

Exit codes

Error messages

Command groups

Next

Configuration

Addressing

​Global flags

​JSON output

​stdout and stderr are separate

​Exit codes

​Error messages

​Command groups

​Next

Configuration

Addressing

Global flags

JSON output

stdout and stderr are separate

Exit codes

Error messages

Command groups

Next