# CLI Client

`sim` is a command-line client for managing simulation sessions without writing code. The tool allows replaying historical slots, injecting modified programs, and analyzing transaction outcomes.

### Installation

Pre-built binaries are available for Linux and macOS (Apple Silicon):

```bash
curl -fsSL https://cli.simulator.termina.technology/install.sh | bash
```

All commands that connect to the simulator require an API key. Pass it via the `--api-key` flag or the `SIMULATOR_API_KEY` environment variable:

```bash
export SIMULATOR_API_KEY=<API_KEY>
```

### Workflow

1. **Check available slots:** `sim ranges` to find a recent slot range to test against.
2. **Run a baseline:** `sim run` + `--program-id` to capture the current behavior.
3. **Build a modified program:** `cargo build-sbf` (or equivalent).
4. **Run with the override:** `sim run` + `--program-so` pointing at the new binary.
5. **Compare the runs:** `sim compare baseline.json experiment.json` to see regressions, improvements, and balance changes.

### Commands

#### `sim ranges`: List Available Slot Ranges

Query for which slot ranges are available to backtest.

```
sim ranges [OPTIONS]
```

```bash
# List all available ranges
sim ranges

# Filter to a specific date window
sim ranges --after 2026-01-01 --before 2026-03-01
```

#### `sim run`: Run a Simulation

Start a simulation session, replay transactions, and stream results to an output file.

```
sim run [OPTIONS] --start-slot <SLOT> --end-slot <SLOT>
```

Run a baseline, then re-run with a modified program binary to compare outcomes:

```bash
# Baseline
sim run \
  --start-slot 400000000 \
  --end-slot 400001000 \
  --program-id <PROGRAM_ID> \
  --output-file baseline.json

# Experiment
# If the new program requires higher CUs, bump it up to prevent transaction failures 
sim run \
  --start-slot 400000000 \
  --end-slot 400001000 \
  --program-id <PROGRAM_ID> \
  --program-so ./target/deploy/program.so \
  --output-file experiment.json \
  --extra-compute-units 200
```

For large slot ranges, split the work across concurrent sessions with `--parallel`:

```bash
sim run \
  --start-slot 400000000 \
  --end-slot 400010000 \
  --parallel
```

To track pre/post account state with each transaction, use `--subscriptions`:

{% code title="" %}

```bash
sim run \
  --start-slot 400000000 \
  --end-slot 400010000 \
  --program-id <PROGRAM_ID> \
  --subscriptions account-diff
```

{% endcode %}

#### `sim compare`: Diff Two Simulation Runs

Compare a baseline run against an experiment run and highlight differences.

```
sim compare <BASELINE> <EXPERIMENT> [SECTION]
```

```bash
sim compare baseline.json experiment.json

# Only show what broke:
sim compare baseline.json experiment.json regressions

# Check P&L impact:
sim compare baseline.json experiment.json balances
```

#### `sim summarize`: Summarize Simulation Outputs

Show metadata and aggregate stats for a simulation output file. Optionally trace balances for specific accounts across all transactions.

```
sim summarize <FILE> [--accounts <ADDRS>]
```

```bash
sim summarize baseline.json

# Trace specific wallets:
sim summarize baseline.json --accounts <WALLET1>,<WALLET2>
```

#### `sim update`: Update the CLI

Downloads and replaces the current `sim` binary with the latest published version.

```bash
sim update
```

### Output Format

`sim run` writes a JSON file with the following structure:

```json
{
  "metadata": {
    "start_slot": 400000000,
    "end_slot": 400001000,
    "program_id": "<PROGRAM_ID>",
    "session_ids": ["..."],
    "timestamp": "2025-01-15T12:00:00Z"
  },
  "transactions": [
    {
      "slot": 400000042,
      "signature": "<BASE58_SIG>",
      "success": true,
      "error": null,
      "logs": ["Program log: ...", "..."],
      "sol_changes": { "<PUBKEY>": -5000000 },
      "token_changes": { "<PUBKEY>": { "<MINT>": -1000 } },
      "account_diffs": { "<PUBKEY>": { "before": "...", "after": "..." } }
    }
  ],
  "summary": {
    "total": 847,
    "successes": 831,
    "failures": 16
  }
}
```

This file is the input for `sim compare` and `sim summarize`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.termina.technology/documentation/tech-setup-guide/cli-client.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.