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