# Commands

> The command reference of the Trajectonomics CLI.

`traj` has 14 top-level commands. Six are groups with their own subcommands — `account`, `baseline`,
`projection`, `report`, `scenario` and `tx` — and the other eight are single commands. `traj help`
lists them and `traj help <command>` shows one command's usage; both are generated from the same
definitions that validate input, so the two cannot drift
([ADR 0015](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0015-command-tree.md)).

## The command tree

| Command | What it does |
| --- | --- |
| [account](https://trajectonomics.com/docs/cli/commands/account/) | Manage the chart of accounts |
| [balance](https://trajectonomics.com/docs/cli/commands/balance/) | Show every account's balance and net worth at a date |
| [baseline](https://trajectonomics.com/docs/cli/commands/baseline/) | Show the Baseline a Projection starts from |
| [export](https://trajectonomics.com/docs/cli/commands/export/) | Write the stored rows into a new directory |
| [fi](https://trajectonomics.com/docs/cli/commands/fi/) | Report the financial independence date under a Scenario |
| [help](https://trajectonomics.com/docs/cli/commands/help/) | Show usage for traj or for one command |
| [init](https://trajectonomics.com/docs/cli/commands/init/) | Create the data directory and an empty database |
| [inspect](https://trajectonomics.com/docs/cli/commands/inspect/) | Show the stored rows of one table, or of every table |
| [projection](https://trajectonomics.com/docs/cli/commands/projection/) | Project the future under a Scenario, and compare two of them |
| [report](https://trajectonomics.com/docs/cli/commands/report/) | Report on the ledger over a period or at a date |
| [scenario](https://trajectonomics.com/docs/cli/commands/scenario/) | Manage Scenarios, the named what-ifs |
| [schema](https://trajectonomics.com/docs/cli/commands/schema/) | Describe the commands and the error registry |
| [tx](https://trajectonomics.com/docs/cli/commands/tx/) | Manage ledger transactions |
| [version](https://trajectonomics.com/docs/cli/commands/version/) | Print the CLI version |

A group needs a subcommand: `traj tx` on its own is invalid input (exit code `2`), and the message
names the command that lists its subcommands, `traj help tx`.

## Global options

Every command accepts:

- `--json` — print JSON; errors become a JSON envelope on stderr.
- `-h`, `--help` — show usage.
- `-v`, `--version` — print the version.

A bare `--` ends flag parsing: nothing after it counts as a flag.

## Exit codes

`0` ok, `1` unexpected, `2` invalid input, `3` domain rejection, `4` not found, `5` conflict
([ADR 0010](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0010-output-contract.md)).

## Errors

In JSON mode a failure is a JSON envelope on stderr, where `code` names the failure and `exitCode`
names its class; both come from one registry that `traj schema` prints
([ADR 0013](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0013-self-describing-error-envelope.md)):

```json
{"error":{"code":"not_found","exitCode":4,"message":"The requested resource was not found."}}
```

Outside JSON mode the same failure is text on stderr with the same exit code. Commands never prompt.

## Document input

Some commands take a JSON document beside the flag form — `--postings` on `tx add` and `tx amend`,
`--file` on `scenario apply` — named by a path, or `-` to read it from stdin
([ADR 0020](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0020-a-leaf-may-declare-a-document-schema.md)).
The transaction document those `--postings` flags read is on
[the `tx` page](https://trajectonomics.com/docs/cli/commands/tx/#the-transaction-document).

## Decisions

- [ADR 0010: explicit output format, JSON error envelope, fixed exit codes](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0010-output-contract.md)
- [ADR 0013: the error envelope names its own exit class](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0013-self-describing-error-envelope.md)
- [ADR 0015: commands form a tree, flags come from the input schema](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0015-command-tree.md)
- [ADR 0020: a leaf may declare a document schema, and `-` reads it from stdin](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0020-a-leaf-may-declare-a-document-schema.md)

Source: [`trajectonomics/cli`](https://github.com/trajectonomics/cli).

Part of the [Docs index](https://trajectonomics.com/docs/llms.txt).
