---
title: CLI (scailog)
path: reference/cli
status: published
---

# CLI (scailog)

`scailog` is the operator CLI: a thin, typed client over the server's `/v1`
API. It reads its server URL, default tenant, and credential from environment
variables and `~/.config/scailog/config.toml`, then calls the same endpoints
documented in the [HTTP API](/docs/scailog/reference/http-api) reference. This
page lists every subcommand and its flags, grounded in `cli/main.py`.

Every command accepts `--tenant` to override the configured default tenant
(shown per-command below only where the command uses it). A `401` from the
server prints a "not authenticated" hint; any other `4xx`/`5xx` prints the
status and body and exits non-zero.

## Credential precedence

The CLI resolves the bearer token to send in this order:

1. An explicit `SCAILOG_API_KEY` environment variable (the scripting override).
2. A valid OIDC session from `scailog login` (auto-refreshed if it has a
   refresh token).
3. The `api_key` in `config.toml`.

OIDC is optional; the API key is always the base mechanism. The OIDC session is
stored separately (`~/.config/scailog/credentials.json`, mode 0600) from the
static config.

## Query and read commands

### scailog query

Query stored entries. Flags: `--tenant`, `--service`, `--site`, `--level`,
`--since`, `--until`, `--subject`, `--q`, `--limit` (default `100`), `--json`.

```bash
scailog query --tenant default --level error --limit 50
scailog query --service billing --q "charge failed" --json
```

### scailog tail

Live tail via server-sent events, printing each entry as it arrives. Flags:
`--tenant`, `--service`, `--level`, `--q`.

```bash
scailog tail --service billing --level warn
```

### scailog sites

List observed call sites. Flags: `--tenant`, `--service`, `--auto-only`,
`--pi-only`, `--diff` (show drift versus the last CI manifest), `--json`. With
`--diff`, sites that emit undeclared PI, `AUTO-*` sites, and declared-but-unseen
sites are flagged.

```bash
scailog sites --service billing --diff
```

### scailog explain

Show why one entry was stored as it was (the resolved policy decision per PI
field). Argument: `<event_id>`. Flag: `--tenant`.

```bash
scailog explain 01J8ZK... --tenant default
```

## DSAR and erasure commands

### scailog dsar

Run a Data Subject Access Request and print (or write) the signed report.
Argument: `<subject_id>`. Flags: `--tenant`, `--out <file>` (write the JSON
report to a file instead of printing it).

```bash
scailog dsar user-42 --out user-42-dsar.json
```

### scailog erase

Crypto-shred a subject. Argument: `<subject_id>`. Flags: `--tenant`,
`--confirm` (skip the interactive prompt), `--mode` (`tombstone` default, or
`delete`). Without `--confirm` it prompts before the irreversible shred.

```bash
scailog erase user-42 --confirm
```

## Policy commands (`scailog policy ...`)

- `scailog policy show [--tenant]` — print the active policy version and YAML.
- `scailog policy edit <file> [--tenant]` — upload the YAML in `<file>` as a new
  version; prints the stored version and any validation warnings.
- `scailog policy history [--tenant]` — list past versions with their
  effective-from timestamps.

```bash
scailog policy edit policy.yaml --tenant default
```

## Key commands (`scailog keys ...`)

- `scailog keys list` — table of `key_id`, `prefix`, `role`, `tenant`,
  `revoked`.
- `scailog keys create <role> [--tenant-scope *] [--service a,b]` — create a key
  and print the plaintext once. `--service` is a comma-separated service scope.
- `scailog keys revoke <key_id>` — revoke a key.

```bash
scailog keys create log_writer --tenant-scope default --service billing
```

## Audit commands (`scailog audit ...`)

- `scailog audit findings [--tenant] [--status open]` — list audit findings.
- `scailog audit resolve <finding_id> [--action fixed] [--tenant]` — resolve a
  finding.
- `scailog audit redact --service <s> --site <id> --fields a,b [--tenant]
  [--finding <id>] [--confirm]` — scrub named plaintext fields to
  `[AUDIT_REDACTED]` across a call site (requires a `dpo` credential;
  irreversible). Without `--confirm` it prompts first.

```bash
scailog audit redact --service billing --site BILLING-CHARGE-OK \
  --fields email,phone --confirm
```

## Authentication commands

### scailog login

Log in via the OIDC device flow (RFC 8628). Flags: `--oidc-url`, `--client-id`
(else taken from `SCAILOG_OIDC_BASE_URL` / `SCAILOG_OIDC_CLIENT_ID` or the
`[oidc]` config section), `--scope` (default `openid profile email`), `--open`
(open the verification URL in a browser). On success it stores the session and
confirms the server accepts the token via `/v1/whoami`.

```bash
scailog login --open
```

### scailog logout

Clear the stored OIDC session. The static API key, if any, keeps working.

### scailog whoami

Show the principal the server resolves for the current credential (calls
`/v1/whoami`).

## Report-key commands (`scailog report-key ...`)

- `scailog report-key show` — list published report public keys (active +
  retired).
- `scailog report-key rotate [--confirm]` — rotate the report signing key
  (requires `dpo`); old reports and receipts stay verifiable.
- `scailog report-key verify <file>` — verify a downloaded DSAR report or
  erasure receipt offline against the server's published report keys. Needs the
  `cryptography` package installed.

```bash
scailog report-key verify user-42-dsar.json
```

## Status

### scailog status

Print the server `/v1/status` document (counters and the active report public
key) as JSON.