Skip to Content
Commands

scenario

Manage Scenarios, the named what-ifs.

traj scenario manages Scenarios, the named what-ifs. A Scenario is a JSON document, and an override changes one value in it by a dotted path with stable ids, such as flows.salary.amount. traj scenario apply --template prints a document to start from. 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. The latest release prints:

traj scenario apply --template
{
  "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. 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
  • --parents <number> — parents aged 60 or over with income of at most 30,000 THB whom the taxpayer supports; needs --tax
  • --disabled-care <number> — relatives with a disability the taxpayer cares for; needs --tax
  • --social-security <number> — social security contributions paid in the tax year, in THB; needs --tax
  • --life-insurance <number> — life insurance premiums paid in the tax year, in THB; needs --tax
  • --health-insurance <number> — the taxpayer’s own health insurance premiums, in THB; needs --tax
  • --parent-health-insurance <number> — health insurance premiums paid for the taxpayer’s parents, in THB; needs --tax
  • --spouse-life-insurance <number> — life insurance premiums paid for a spouse with no income, in THB; needs --tax and a filing status that allows the spouse allowance
  • --mortgage-interest <number> — home-loan interest paid in the tax year, in THB; needs --tax
  • --donation2x <number> — donations that the statute counts twice, such as education and hospitals, in THB; needs --tax
  • --donation1x <number> — donations counted once, in THB; 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

The filing statuses are single, married_no_income_spouse, married_separate, married_joint and married_separate_40_1_joint_rest. The deduction flags state what the taxpayer paid; the statutory ceilings are applied by the tax core, not by the command. traj help scenario tax lists every accepted --label value.

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 --tax th-2026 --filing-status married_no_income_spouse --life-insurance 20000 --mortgage-interest 30000 --social-security 9000 --donation1x 5000 --label salary=income.section40_1  # The same Levy with the deductions a Thai employee usually has.
traj scenario tax base --none                                                                                                                                                                              # Take the tax Levy out, so the figures are pre-tax again.

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