@blankstate/cli

Terminal interface for Blankstate. Measure interactions, inspect protocols, run programmatic dives against published Stages, and monitor your AI agents in real time — from the command line.

Install

npm install -g @blankstate/cli

Or run without installing:

npx @blankstate/cli status

Authentication

# Interactive login — stores token in ~/.blankstate/config.json
bks auth login

# Check current auth and ICS balance
bks auth status

# Logout
bks auth logout

# Or set via environment variable (takes priority over saved config)
export BLANKSTATE_API_TOKEN=bks_your_token_here

Get a token at atlas.blankstate.ai.

Commands

bks status

API health, engine versions, and ICS balance.

$ bks status

  API:           healthy
  Authenticated: true
  SGM versions:  1.0 · 1.5

  ICS cap:       40
  ICS used:      4
  ICS remaining: 36
  Period:        2026-03

bks protocol list

List protocols in your account.

$ bks protocol list

  50 protocol(s):

  Customer Support Quality
    ID:       proto-6d28a7b8-a905-45f3-81f5-2cd574813450
    Versions: 0.1, 0.2
    SGM:      1.0

  Agent Safety Monitor
    ID:       proto-f302e022-1ed2-4546-abcb-e942239d5c79
    Versions: 1.0
    SGM:      1.5

bks protocol inspect <id>

Full protocol definition with metamarkers.

bks protocol inspect proto-6d28a7b8-a905-45f3-81f5-2cd574813450

# Save a local YAML snapshot
bks protocol inspect proto-6d28a7b8-a905-45f3-81f5-2cd574813450 --save

  Customer Support Quality
  ────────────────────────
  ID:          proto-6d28a7b8-a905-45f3-81f5-2cd574813450
  Version:     0.2
  SGM:         1.0

  Metamarkers (9):
    - Solution-Oriented
    - Empathy
    - Professional Tone
    - Acknowledgment
    - Clarity
    ...

--save writes a .yaml file to ~/.blankstate/protocols/.

bks sense <protocol> <content>

Measure content against a protocol.

# Inline text
bks sense proto-xxx:1.0 "The agent resolved the customer's issue with clear steps."

# From a file
bks sense proto-xxx:1.0 --file transcript.txt

# Options
bks sense proto-xxx:1.0 "..." --profile discovery
bks sense proto-xxx:1.0 "..." --depth full
bks sense proto-xxx:1.0 "..." --save md         # save trace to ~/.blankstate/measurements/
bks sense proto-xxx:1.0 "..." --save yaml
bks sense proto-xxx:1.0 "..." --save both

  Protocol:   Customer Support Quality  (proto-xxx:1.0)
  Score:      0.82
  Fidelity:   0.74 (sufficient)
  SGM:        1.0
  ICS:        2 consumed

  Resonance:
    ████████████████████  0.96  Solution-Oriented
    ██████████░░░░░░░░░░  0.51  Empathy
    ████░░░░░░░░░░░░░░░░  0.21  Professional Tone
    ██░░░░░░░░░░░░░░░░░░  0.10  Acknowledgment
    █░░░░░░░░░░░░░░░░░░░  0.02  Escalation Risk

  ICS pool:  4/40 used · 36 remaining

| Flag | Description | |------|-------------| | --file <path> | Read content from file | | --language <code> | Language code (default: en) | | --profile <type> | raw | detailed | discovery | | --depth <level> | measure (scores only) | full (+ entities, evidence) | | --detail | Show full resonance decomposition inline | | --save <format> | md | yaml | both — save artifact to ~/.blankstate/measurements/ | | --trace | Alias for --save md |

bks session <protocol> [protocol...]

Interactive sensing session. Type content, get a measurement. Ctrl+C to exit.

# Inline session — single protocol, stays in your terminal
bks session proto-xxx:1.0

# Multi-protocol full-screen TUI dashboard
bks session proto-aaa:1.0 proto-bbb:2.0 --tui

# Pipe agent output
my-agent | bks session proto-xxx:1.0 --pipe

# Watch a log file for new lines
bks session proto-xxx:1.0 --watch ./agent-output.log

# Save session log
bks session proto-xxx:1.0 --tui --log

TUI dashboard (--tui) opens a full-screen panel view:

• One colored spectral waveform per protocol — the heartbeat of your session
• Live resonance bars for the active protocol
• Signal analysis (v1.5 protocols: spread, coherence, dominant mode)
• Timestamped activity log with Chronicle (C×B×I interaction contexts) and Journey trail
• ICS consumption bar

| Command | Description | |---------|-------------| | /list | Browse and add protocols interactively | | /add <id:ver> | Add a protocol by ID directly | | /chronicle | Cycle through C×B×I interaction context views | | /sessions | Browse saved session history | | /mini / /full | Toggle compact or full dashboard | | /clear | Reset the activity log | | Tab | Cycle active protocol | | /q | Quit (auto-saves session) |

| Flag | Description | |------|-------------| | --tui | Full-screen multi-protocol dashboard | | --pipe | Read interactions from stdin | | --watch <file> | Tail a file for new interactions | | --log | Save session to ~/.blankstate/sessions/ | | --language <code> | Language code (default: en) |

bks dive

Turn-based session against a published Stage. Open a dive, submit actions, inspect status, then close to emit a StageCard. All traffic goes through @blankstate/sdk (Blankstate.dive.*).

# Open a dive
bks dive open stg_credit_advisory_v1
bks dive open stg_credit_advisory_v1 --model gpt-4o --seed 42

# Submit one action (turn auto-advances if you opened the dive with this CLI)
bks dive act dive_01j7 --turn 0 "Inspect the available records"
bks dive act dive_01j7 --file action.txt

# Inspect without advancing the world
bks dive status dive_01j7

# Close and emit a StageCard
bks dive close dive_01j7 --summary "done" --save json

# Interactive REPL: observation → action → reading → …
bks dive session stg_credit_advisory_v1 --save json --log

$ bks dive open stg_credit_advisory_v1

  ┌─ DIVE OPEN ──────────────────────────────────────────────────┐
  │  dive_id:     dive_01j7
  │  stage_id:    stg_credit_advisory_v1
  │  mode:        practice
  │  max_turns:   8
  └──────────────────────────────────────────────────────────────┘

  Observation (turn 0)
  A customer is waiting.

  Next: bks dive act dive_01j7 --turn 0 "<action>"

The session REPL auto-closes on observation.done, a server-emitted StageCard, or envelope.max_turns. Ctrl+C or /q closes early.

| Command | Description | |---------|-------------| | bks dive open <stage_id> | Open a dive against a published Stage | | bks dive act <dive_id> "<action>" | Submit one action | | bks dive status <dive_id> | Inspect a dive without advancing | | bks dive close <dive_id> | Finalise the dive and emit a StageCard | | bks dive session <stage_id> | Interactive REPL (observation → action → …) |

| Flag | Description | |------|-------------| | --model <id> | Agent identifier for replay grouping (open, session) | | --session <id> | Client-supplied session id (open) | | --password <pw> | Password for gated stages (open, session) | | --seed <n> | Deterministic world seed (open, session) | | --turn <n> | Idempotency key; auto-advances from cache if omitted (act) | | --file <path> | Read action payload from file (act) | | --summary <text> | Optional session summary (close) | | --save <json\|yaml> | Save StageCard to ~/.blankstate/stagecards/ (close, session) | | --log | Save transcript to ~/.blankstate/dives/transcripts/ (session) |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | BLANKSTATE_API_TOKEN | API token (overrides saved config) | — | | BLANKSTATE_API_URL | API base URL | https://api.blankstate.ai |

Local Files

The CLI stores config and artifacts in ~/.blankstate/:

| Path | Description | |------|-------------| | ~/.blankstate/config.json | Auth token and API URL | | ~/.blankstate/protocols/ | Protocol snapshots (.yaml, via inspect --save) | | ~/.blankstate/measurements/ | Measurement traces (.md / .yaml, via sense --save) | | ~/.blankstate/sessions/ | Session logs (.md, via session --log) | | ~/.blankstate/dives/ | Cached dive state (.json) | | ~/.blankstate/dives/transcripts/ | Dive session transcripts (.md, via dive session --log) | | ~/.blankstate/stagecards/ | StageCards (.json / .yaml, via dive close --save / dive session --save) |

Requirements

• Node.js >= 20.0.0
• API token from atlas.blankstate.ai
• A terminal that supports ANSI true color for the TUI (Windows Terminal, iTerm2, any modern terminal)

Issues

github.com/blankstate-ai/blankstate-node/issues

License

MIT — blankstate.ai