Skip to Content
Commands

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

CommandWhat it does
accountManage the chart of accounts
backupWrite the one file a restore reads into a new directory
balanceShow every account’s balance and net worth at a date
baselineShow the Baseline a Projection starts from
dataManage the stored data itself
doctorCheck the data directory, the database and the ledger before anything goes wrong
exportWrite the stored rows into a new directory
fiReport the financial independence date under a Scenario
helpShow usage for traj or for one command
initCreate an empty ledger; only restore may also create one
inspectShow the stored rows of one table, or of every table
projectionProject the future under a Scenario, and compare two of them
restoreWrite a backup’s rows into an empty database
reportReport on the ledger over a period or at a date
scenarioManage Scenarios, the named what-ifs
schemaDescribe the commands and the error registry
txManage ledger transactions
versionPrint 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.

Source: trajectonomics/trajectonomics/apps/cli.