# 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](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0024-scenario-documents-and-overrides.md)).
A leaf with a document form may print one template: `traj scenario apply --template` prints a
document the pinned `sim-core` accepts
([ADR 0033](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0033-a-document-leaf-prints-a-template-the-core-accepts.md)).
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. At `@trajectonomics/cli@0.2.0`, the release the Docs Portal documents, it prints:

```json
{
  "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
([ADR 0032](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0032-tax-is-the-scenarios-levy.md)).
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

```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 --none                                                                                      # Take the tax Levy out, so the figures are pre-tax again.
```

## Decisions

- [ADR 0016: deletion has three names, and only one is a tombstone](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0016-three-deletion-stories.md)
- [ADR 0024: Scenario documents are `sim-core`'s, and Overrides use dotted paths](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0024-scenario-documents-and-overrides.md)
- [ADR 0032: tax is the Scenario's Levy](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0032-tax-is-the-scenarios-levy.md)
- [ADR 0033: a document leaf prints one template its core accepts](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0033-a-document-leaf-prints-a-template-the-core-accepts.md)

See [Commands](https://trajectonomics.com/docs/cli/commands/) for the global options, exit codes and error envelope.

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