# Commands

> The command reference of the Trajectonomics CLI.

`traj help` lists the top-level commands below, and `traj help <command>` shows one command's usage;
both are generated from the same definitions that validate input. A group, such as `tx` or
`account`, has its own subcommands; the rest are single commands.

## The command tree

| Command | What it does |
| --- | --- |
| [account](https://docs.trajectonomics.com/cli/commands/account/) | Manage the chart of accounts |
| [backup](https://docs.trajectonomics.com/cli/commands/backup/) | Write the one file a restore reads into a new directory |
| [balance](https://docs.trajectonomics.com/cli/commands/balance/) | Show every account's balance and net worth at a date |
| [baseline](https://docs.trajectonomics.com/cli/commands/baseline/) | Show the Baseline a Projection starts from |
| [data](https://docs.trajectonomics.com/cli/commands/data/) | Manage the stored data itself |
| [doctor](https://docs.trajectonomics.com/cli/commands/doctor/) | Check the data directory, the database and the ledger before anything goes wrong |
| [export](https://docs.trajectonomics.com/cli/commands/export/) | Write the stored rows into a new directory |
| [fi](https://docs.trajectonomics.com/cli/commands/fi/) | Report the financial independence date under a Scenario |
| [help](https://docs.trajectonomics.com/cli/commands/help/) | Show usage for traj or for one command |
| [init](https://docs.trajectonomics.com/cli/commands/init/) | Create an empty ledger; only restore may also create one |
| [inspect](https://docs.trajectonomics.com/cli/commands/inspect/) | Show the stored rows of one table, or of every table |
| [projection](https://docs.trajectonomics.com/cli/commands/projection/) | Project the future under a Scenario, and compare two of them |
| [restore](https://docs.trajectonomics.com/cli/commands/restore/) | Write a backup's rows into an empty database |
| [report](https://docs.trajectonomics.com/cli/commands/report/) | Report on the ledger over a period or at a date |
| [scenario](https://docs.trajectonomics.com/cli/commands/scenario/) | Manage Scenarios, the named what-ifs |
| [schema](https://docs.trajectonomics.com/cli/commands/schema/) | Describe the commands and the error registry |
| [tx](https://docs.trajectonomics.com/cli/commands/tx/) | Manage ledger transactions |
| [version](https://docs.trajectonomics.com/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.

## 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. `hint`, when present, says
what to do next. `traj account show Nope --json` on a ledger with no such account prints:

```json
{"error":{"code":"not_found","exitCode":4,"message":"No account matches \"Nope\".","hint":"Run \"traj account list\" to see the chart.","details":{"resource":"account"}}}
```

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

These codes are worth retrying as they are: `database_busy` and `disk_full`. For every other
failure, running the same command again unchanged gives the same answer. `traj help` lists the
retryable codes, and each code in `traj schema`'s registry carries `retryable`.

A command that reads or writes the ledger fails with `ledger_missing` (exit code `4`) until
`traj init` has created one, and the hint names `traj init`. Only `init` and `restore` create a
ledger; [`traj doctor`](https://docs.trajectonomics.com/cli/commands/doctor/) reports a missing one instead of failing.

## Next steps in a result

A result with nothing to show because the ledger is empty ends with the command to run next: a
`hint:` line in text, and a `hint` field in JSON. On a new ledger, `traj account list` prints:

```text
accounts:
hint: Run "traj account add Cash --type asset --currency THB" to create your first account.
```

A result that is empty because of the date or filter you chose has no hint.

## 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. The transaction
document those `--postings` flags read is on
[the `tx` page](https://docs.trajectonomics.com/cli/commands/tx/#the-transaction-document).

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

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