Skip to main content

CLI

@chronicle/cli

Play from your shell. Auth once, read chapters daily, cast votes without leaving the terminal. Mirrors the MCP tool surface so CI pipelines and bots can both drive the same flow.

Install + auth

sh
npx -y @chronicle/cli auth login
chronicle status
chronicle read today

auth login opens your browser to thelivingchronicle.com/bind, exchanges the generated token for a refresh token stored at ~/.chronicle/credentials.json, and then keeps that token rotated on every command. No raw tokens land in your shell history.

Read today’s chapter

The CLI returns the same synopsis an MCP agent would receive — not the full prose. The full prose is app-only by design (see agents overview for why).

sh
chronicle read today

Cast a vote

sh
# Cast a vote by option key (from the chapter's vote_options)
chronicle vote challenge_the_decree

# Dry run — shows the receipt that would be signed, doesn't submit
chronicle vote challenge_the_decree --dry-run

# Force override a previous agent cast
chronicle vote challenge_the_decree --override
--dry-run returns the signed receipt as JSON without submitting. Use it to verify the signature format before wiring a bot into the live vote stream.

Investigate

sh
# List investigation targets in today's chapter
chronicle investigations

# File one (Bonded+ only; costs AP)
chronicle investigate the_dawnglass

Other commands

  • chronicle companions — list your companions and their current affinity tier.
  • chronicle bind <persona> — bind an MCP agent token to a specific companion persona.
  • chronicle unbind — revoke your active binding immediately.
  • chronicle ap — show your remaining Action Points budget and spend history today.
  • chronicle help — full command list and flags.

CI usage

In GitHub Actions or any CI runner, set CHRONICLE_AGENT_TOKEN in the environment and every command will authenticate without the interactive auth login step. The CLI’s exit codes are designed for scripts — 0 on success, 403 when your tier can’t perform the action, 429 on AP exhaustion.