Quickstart.

Five minutes from install to first signed check.

1 · Install the wallet

During private alpha, distribution is via signed tarball. Once you have access:

# macOS / Linux / Windows — unzip + run
./the-wallet

The wallet opens its own window, prompts for a password to initialize the local vault, and starts the HTTP API on 127.0.0.1:9473. All subsequent CLI / SDK calls hit that local API.

2 · Register a consumer

A consumer is an app that's allowed to talk to Token Holder. Every request needs a consumer id.

TOKEN_HOLDER_CONSUMER=owner th consumers register my-app \
  obsidian_vault:read,obsidian_vault:write,api_keys:read

This mints a per-app bearer token at ~/.clawnoly/tokens/my-app.token and declares the maximum scope surface this consumer can ever request.

3 · Issue a grant

Scopes are a ceiling; grants are the actual permissions. Issue one for the paths your app will touch.

TOKEN_HOLDER_CONSUMER=owner th grants create my-app obsidian_vault read \
  --paths='Projects/**,README.md'

4 · Make your first signed check

From your app, ask: "am I allowed to read that file?"

TOKEN_HOLDER_CONSUMER=my-app th grants check obsidian_vault read \
  --path='Projects/notes.md'

# → allowed  signed=true  agent_id=null  (Option A claim path)

To upgrade to a cryptographically signed request (Option B), mint an agent identity the CLI can use:

TOKEN_HOLDER_CONSUMER=my-app th agents register research-bot-v1 \
  --name='Research bot' --generate

# → agent_id=...  private_key=...  (stored locally, used per-request)

5 · Inspect the audit chain

Every check, allow or deny, landed in the signed chain.

TOKEN_HOLDER_CONSUMER=owner th audit head
# → head_hash=a3b1c097…  chained_rows=4  pre_chain_rows=0

TOKEN_HOLDER_CONSUMER=owner th audit verify
# → ✓ chain valid  rows_verified=4  pre_chain=0

As a consumer you can pull your own audit trail without admin scope:

TOKEN_HOLDER_CONSUMER=my-app th my usage history