Skip to Content
Commands

scenario

Manage Scenarios, the named what-ifs.

traj scenario manages Scenarios, the named what-ifs. A Scenario’s document is sim-core’s, and overrides use dotted paths with stable ids (ADR 0024). A leaf with a document form may print one template: traj scenario apply --template prints a document the pinned sim-core accepts (ADR 0033). A Scenario can also carry a tax Levy, which its Projection applies.

traj scenario apply <name>

Create or update a Scenario from a JSON document.

  • --file <string> — the JSON document’s path, or - for stdin; required unless --template
  • --template — print a complete document to start from and open no Data directory; takes no name
  • --dry-run — report the row and roll the write back
traj scenario apply --template > base.json           # Print the document to start from.
traj scenario apply base --file base.json            # Create a Scenario, or update it when the document changed.
traj scenario apply base --file - < base.json        # Read the document from stdin.
traj scenario apply base --file base.json --dry-run  # Show the row and roll the write back.

traj scenario apply --template prints a complete document to start from: print it, edit it, then apply it. At @trajectonomics/cli@0.2.0, the release the Docs Portal documents, it prints:

{
  "schemaVersion": 4,
  "currency": "THB",
  "economy": {
    "inflation": 0
  },
  "accounts": [
    {
      "id": "cash",
      "kind": "asset",
      "rate": 0
    }
  ],
  "flows": [
    {
      "id": "salary",
      "kind": "income",
      "earned": true,
      "amount": 100000,
      "frequency": "monthly",
      "start": "2026-01-01",
      "growth": "inflation"
    }
  ],
  "cashflow": {
    "surplus": [
      {
        "account": "cash"
      }
    ],
    "contribute": [],
    "withdraw": []
  }
}

traj schema scenario apply names the document version the installed CLI accepts, so print the template rather than copying this one into a newer CLI.

Amounts are integer minor units (cents or satang, depending on the currency), rates and inflation are integer basis points, and dates are YYYY-MM-DD. growth is "inflation" or { "bps": <integer> }. cashflow.surplus is the order surplus fills Accounts, cashflow.contribute is the funding priority for contributions, and cashflow.withdraw is the withdrawal order.

traj scenario diff <a> <b>

Compare two Scenario documents path by path.

traj scenario diff base early  # Show what a what-if changed.
traj scenario diff base base   # Compare a Scenario with itself.

traj scenario fork <from> <name>

Copy a Scenario under a new name.

  • --set <string> — replace one existing dotted document path with a JSON value; repeatable
  • --dry-run — report the row and roll the write back
traj scenario fork base early                                  # Copy a Scenario under a new name.
traj scenario fork base early --set flows.salary.amount=50000  # Copy it with one assumption changed.

traj scenario list

List the live Scenarios by name.

traj scenario list --json  # Show the Scenarios as JSON.

traj scenario rm <scenario>

Tombstone a Scenario and free its name.

  • --dry-run — report the row and roll the write back
traj scenario rm early            # Retire a Scenario by name.
traj scenario rm early --dry-run  # Show what rm would do.

traj scenario show <scenario>

Show one Scenario with its document.

traj scenario show base                                 # Show a Scenario by name.
traj scenario show base --json | jq .scenario.document  # Print only the document.

traj scenario tax <scenario>

Write or remove the tax Levy a Scenario’s labelled Flows are taxed under (ADR 0032). A Levy tallies labels and never guesses them, so --label says which Section 40 class each income Flow belongs to.

  • --tax <string> — write the Levy for this jurisdiction: th-2026, Thailand’s 2026 income tax
  • --filing-status <string> — the taxpayer’s filing status; needs --tax, defaults to single
  • --children <number> — children counted for the child allowance; needs --tax, defaults to 0
  • --children-at-higher-rate <number> — children born 2018 or later, allowed at the higher rate; a subset of --children, needs --tax
  • --label <string> — classify one Flow for tax as <flow>=<label>, such as salary=income.section40_1; repeatable, needs --tax
  • --none — remove the tax Levy instead of writing one
  • --dry-run — report the row and roll the write back
traj scenario tax base --tax th-2026 --label salary=income.section40_1                                             # Charge Thailand's 2026 income tax on the salary this Scenario declares.
traj scenario tax base --tax th-2026 --filing-status married_joint --children 1 --label salary=income.section40_1  # The same Levy under a married-joint profile with one child.
traj scenario tax base --none                                                                                      # Take the tax Levy out, so the figures are pre-tax again.

Decisions

See Commands for the global options, exit codes and error envelope.