> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> How the jstm command line works — global flags, JSON output, streams, and exit codes.

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

```bash theme={null}
jstm --help
jstm commands       # print the entire command tree
jstm --version      # or -V
```

<Note>
  `jstm` and `joystream` are the same program. The prebuilt binary is named `joystream`; `jstm` is the short alias. These docs use `jstm`.
</Note>

## 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.

```bash theme={null}
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:

```bash theme={null}
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](/cli/auth)             | `init`, `login`, `logout`, `whoami`                                      |
| [`agent`](/cli/agent-plan)              | Plan, build, conform, promote, run, inspect, manage, and schedule agents |
| [`ticket`](/cli/ticket)                 | Read a run's work as tickets                                             |
| [`workspace`](/cli/workspace)           | Create, list, switch workspaces and manage members                       |
| [`org`](/cli/org)                       | Organizations, members, invitations                                      |
| [`profile`](/cli/profile)               | Username and email management                                            |
| [`vault`](/cli/vault)                   | Vaults, credentials, audit, and scope                                    |
| [`connection`](/cli/connection)         | Service connections                                                      |
| [`mcp`](/cli/mcp)                       | MCP server catalog, endpoints, and repositories                          |
| [`skills`](/cli/skills)                 | Skills catalog and source repositories                                   |
| [`registry`](/cli/registry)             | The resolved catalog, with tier precedence                               |
| [`session`](/cli/session)               | Pin skills to a builder session                                          |
| [`triggers`](/cli/triggers)             | Trigger bindings, webhooks, and events                                   |
| [`input-requests`](/cli/input-requests) | Answer an agent that's waiting on input                                  |
| [`credits`](/cli/credits)               | Balance and ledger                                                       |
| [`admin`](/cli/admin)                   | User administration for self-hosted operators                            |

`jstm commands` always reflects the version you have installed.

## Next

<Columns cols={2}>
  <Card title="Configuration" href="/cli/configuration" icon="settings">
    Config paths, environment variables, and precedence.
  </Card>

  <Card title="Addressing" href="/cli/addressing" icon="at-sign">
    Handles, UUIDs, FQNs, and run addresses.
  </Card>
</Columns>