Skip to content
Memtru
Documentation menu
Reference

CLI reference

memtru [COMMAND] [OPTIONS]

Every command supports --help.

Exit codes

Code Meaning
0 Completed with no FAIL or ERROR. INCONCLUSIVE is allowed unless the inconclusive policy is on.
1 At least one scenario FAILED (test), or the head run has new failures (compare).
2 Usage or configuration error (invalid YAML, unknown scenario, unsafe target).
3 Execution error: a scenario ERRORED, or nothing was executed (all skipped).
4 INCONCLUSIVE results with --fail-on-inconclusive or ci.fail_on_inconclusive: true.
5 Cloud command failed (auth, upload).
130 Interrupted.

FAIL takes precedence over ERROR, which takes precedence over INCONCLUSIVE.

version

Prints the CLI and report schema versions.

init

memtru init [--path memtru.yaml] [--project NAME] [--force]

Writes a validated configuration using the in_memory adapter. Refuses to overwrite without --force.

doctor

memtru doctor [--config memtru.yaml] [--connectivity]

Checks Python, the installed version, configuration validity, adapter construction, credentials named by token_env (presence only), capabilities, report directory permissions, selected scenarios and cloud credentials. For http adapters the target is contacted only with --connectivity. Exit 0 when nothing failed, 2 otherwise.

adapters

Lists built-in adapter types and how each is verified.

scenarios

Lists scenario ids, slugs, versions, modes and required capabilities.

test

memtru test [--config FILE] [--scenario ID_OR_SLUG ...] [--output-dir DIR]
                 [--fail-on-inconclusive | --allow-inconclusive]
                 [--branch NAME] [--commit SHA] [--quiet] [--json]

Runs the configured scenarios (or those given with -s/--scenario, repeatable; afterlife selects MT-AF-001 and MT-AF-002) and writes reports to report.output_dir (default .memtru/reports) as <run-id>.<format> plus latest.<format>.

  • --json prints the JSON report to stdout and progress to stderr, for piping.
  • --quiet prints only the summary.
  • --branch and --commit are recorded in the report. In GitHub Actions they default to GITHUB_HEAD_REF/GITHUB_REF_NAME and GITHUB_SHA.

The CLI is non-interactive during test, so it is safe in CI.

report

memtru report [REPORT.json] [--format html|json] [--output FILE]

Validates a saved JSON report and renders it. HTML goes next to the input by default; JSON goes to stdout.

compare

memtru compare BASE.json HEAD.json [--json]

MT-REG-008. Prints a per-scenario change table, configuration differences and capability changes. Exit 1 if the head run has new failures.

demo

memtru demo [--output-dir .memtru/demo] [--afterlife]

Runs every scenario against the built-in store with ignore_user_scope, then without it, writes both reports and prints the comparison. Both runs execute the real scenario logic.

With --afterlife it runs MT-AF-001 and MT-AF-002 against a store with late_write_resurrection and history_reingestion, then a correct store, and writes the reports to <output-dir>/afterlife.

auth login

memtru auth login [--url https://memtru.com] [--token-stdin]

Verifies the token with the server (GET /api/cli/whoami), then stores URL and token in ~/.memtru/credentials.json (or $MEMTRU_HOME/credentials.json), with file mode 600 where the OS supports it. Prompts with hidden input unless --token-stdin. Remote URLs must use https.

In CI, set MEMTRU_TOKEN (and MEMTRU_URL for a self-hosted server; it defaults to https://memtru.com) instead; they take precedence over the stored file.

auth status

Shows the server, token prefix, source, project, scopes and expiry. Never prints the token.

auth logout

Deletes the stored credentials file. Revoke the token in the dashboard as well.

upload

memtru upload [REPORT.json] [--url URL] [--dry-run] [--yes]

Builds a sanitized copy of the report (see Report sanitization), prints a preview of what will be sent, asks for confirmation unless --yes, and posts it to /api/report-upload with an Idempotency-Key equal to the run id. Re-uploading the same run is reported as already uploaded. Nothing is uploaded automatically by any other command.

Configuration file

version: 1
project:
  name: example-agent            # letters, digits, . _ - and spaces
adapter:
  type: in_memory                # in_memory | http | custom (see Adapters)
execution:
  environment: sandbox           # local | sandbox | staging | production
  allow_production: false        # production is refused unless true
  timeout_seconds: 30            # per scenario attempt, 0-300
  max_concurrency: 2             # scenarios in parallel, 1-8
  retries: 1                     # extra attempts on transient provider errors, 0-3
  consistency:
    attempts: 5                  # polls for visibility / deletion, 1-20
    interval_ms: 200             # between polls, 0-10000
scenarios: all                   # or a list of ids / slugs
report:
  formats: [json, html]
  output_dir: .memtru/reports
privacy:
  include_raw_content: false     # true embeds fixture text in evidence
  redact_secrets: true
ci:
  fail_on_inconclusive: false

Unknown keys are rejected with the path of the offending field.