# 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

```bash
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:

```bash exec
traj scenario apply --template
```

```json output
{
  "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.

```bash
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

```bash
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.

```bash
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

```bash
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.

```bash
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.

```bash
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](https://docs.trajectonomics.com/cli/commands/) for the global options, exit codes and error envelope.

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