@blankstate/cli

Terminal interface for Blankstate. Measure interactions, inspect protocols, 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) |

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) |

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