CLI Reference

Complete command reference for the tell command-line tool.

$ npm install -g @tell-protocol/cli

Portfolio Directory

Running tell init creates a .tell/ directory with support for multiple named portfolios.

.tell/
  active                       # Plain text: active portfolio slug
  portfolios/
    acme-corp/
      portfolio.tell.json      # Portfolio state
      config.json              # Remote connections
      evidence/
        asm_xxx.jsonl           # Append-only evidence per assumption
      history/
        v001.tell.json          # Portfolio snapshots per version
      audit.jsonl               # Append-only audit log
    mobile-app/
      portfolio.tell.json
      ...

Evidence uses JSONL format (one JSON object per line) so that appends produce clean single-line diffs. Legacy single-portfolio layouts are auto-migrated on first access.

Interactive REPL

Run tell with no arguments to enter interactive REPL mode. The prompt shows the active portfolio name.

$ tell
  The Tell Protocol CLI — encode strategic intent

  Type a command, or help for available commands. exit to quit.

tell (acme-corp) > status
  Acme Corp — v7
  Bets:  2 active
  Assumptions:  4 (2 holding, 1 pressure, 1 unknown)

tell (acme-corp) > portfolio switch mobile-app
  ✓ Switched to portfolio "mobile-app"

tell (mobile-app) >

All commands work the same in REPL mode — omit the tell prefix. The guided onboarding wizard runs automatically on first use.

Commands

tell init

tell init [--name <name>] [--org <org>]

Initialise a new Tell portfolio in the current directory. Creates a .tell/ directory with the portfolio file, evidence store, and version history.

tell bet add

tell bet add "<thesis>" [--horizon <horizon>] [--stage <stage>]

Add a new bet to the portfolio. The thesis should be a falsifiable hypothesis. Horizon accepts values like 6m, 12m, 2y. Stage can be exploring, validating, committed, or scaling.

tell bet list

tell bet list

List all bets with their status, confidence, and assumption count.

tell bet kill

tell bet kill <bet-id>

Kill a bet, setting its status to killed. This is irreversible — the bet remains in the portfolio for audit purposes.

tell bet succeed

tell bet succeed <bet-id>

Mark a bet as succeeded.

tell bet stage

tell bet stage <bet-id> <stage>

Set the investment stage of a bet. Stage must be exploring, validating, committed, or scaling. Stage is orthogonal to status — it tracks where a bet is in its investment lifecycle.

tell assume add

tell assume add <bet-id> "<statement>"

Add an assumption to a bet. The statement should describe a condition that must be true for the bet to hold.

tell assume list

tell assume list <bet-id>

List all assumptions for a given bet.

tell assume link

tell assume link <assumption-id> <bet-id>

Link an existing assumption to another bet, creating a many-to-many relationship for shared assumptions across bets.

tell evidence add

tell evidence add <assumption-id> "<summary>" --signal <signal> [--confidence <level>] [--source <type>]

Append evidence to an assumption. Signal must be supports, weakens, or neutral. Confidence is high, medium, or low. Evidence is immutable once recorded.

tell evidence list

tell evidence list <assumption-id>

List all evidence for a given assumption.

tell status

tell status

Show a portfolio health overview including bet counts by status, assumption counts by status, evidence totals, and connection counts.

tell stale

tell stale [--days <threshold>]

Find assumptions that lack recent evidence. Default threshold is 14 days. Stale assumptions indicate potential blind spots in your strategic model.

tell risk

tell risk

Portfolio risk assessment. Shows shared assumptions (single points of failure), failing assumptions, resource conflicts, and escalated connections.

tell export

tell export [-o <file>]

Export the complete portfolio as a .tell.json file. Defaults to portfolio.tell.json. The exported file conforms to the Tell v0.2 specification.

tell validate

tell validate <file>

Validate a .tell.json file against the Tell Protocol schema. Reports any validation errors with paths to the invalid fields.

tell connect add

tell connect add <bet-a> <bet-b> --type <type> "<description>"

Add a connection between two bets. Type must be tension, synergy, dependency, or resource_conflict.

tell connect list

tell connect list

List all connections between bets.

tell experiment add

tell experiment add <bet-id> "<hypothesis>" --method "<method>" --success "<criteria>" [--cost <ceiling>] [--timebox <duration>]

Add a new experiment to validate a bet. Requires a hypothesis, method, and success criteria. Optionally set a cost ceiling and time box.

tell experiment list

tell experiment list [--bet <bet-id>]

List all experiments, optionally filtered by bet ID.

tell experiment start

tell experiment start <experiment-id>

Start a planned experiment, setting its status to running.

tell experiment conclude

tell experiment conclude <experiment-id> --signal <signal> --summary "<summary>"

Conclude an experiment with an outcome. Signal must be supports, weakens, or neutral.

tell experiment abandon

tell experiment abandon <experiment-id>

Abandon an experiment without an outcome.

tell auth logout

tell auth logout [--host <url>]

Remove stored credentials for a platform host.

tell auth status

tell auth status

Show current authentication status — which platform hosts you are logged into.

tell remote add

tell remote add <name> <url>

Add a remote platform connection to this portfolio. The name is a short alias (e.g., "origin") and the URL points to an Apophenic platform instance.

tell remote list

tell remote list

List all configured remotes for this portfolio.

tell remote remove

tell remote remove <name>

Remove a remote connection from this portfolio.

tell push

tell push [remote]

Push this portfolio and all evidence to a remote platform. Defaults to the "origin" remote. On first push, creates a new portfolio on the platform and links it for future syncs.

tell pull

tell pull [remote] [--force]

Pull portfolio updates from a remote platform. Compares versions and warns if local is ahead of remote. Use --force to overwrite local changes.

tell portfolio list

tell portfolio list

List all portfolios under the current .tell/ directory, marking the active portfolio.

tell portfolio switch

tell portfolio switch <name>

Switch the active portfolio. All subsequent commands will operate on this portfolio.

tell portfolio current

tell portfolio current

Show details of the active portfolio including name, organisation, version, and bet count.

tell portfolio remove

tell portfolio remove <name>

Remove a portfolio. If the removed portfolio was active, automatically switches to another available portfolio.