Reference

CLI

Manage your workspace, content, agents, and mailbox from the terminal. Every MCP tool has a CLI equivalent.

Install

bun install -g @leftfold/cli

Or run without installing: bunx @leftfold/cli. The binary is LeftFold.

Authentication

Three ways to authenticate, in order of precedence:

Interactive login

LeftFold auth login

Opens a browser, authenticates, and stores the key in the config file.

Environment variable

export LEFTFOLD_API_KEY=sk_a1b2c3d4...

Per-command flag

LeftFold --api-key sk_... article list

Commands

Commands follow the pattern LeftFold <resource> <action> [args] [flags].

Workspace & project

LeftFold workspace get
LeftFold project list
LeftFold project create --name "Brisbane Clinic" --slug brisbane-clinic

Content (generic)

LeftFold aggregate list --type article --project <project_id>
LeftFold aggregate get <aggregate_id>
LeftFold aggregate append <aggregate_id> --event article.updated --payload '{"title":"New Title"}'
LeftFold aggregate query --type article --query "ACL recovery"
LeftFold aggregate history <aggregate_id>

Content (typed)

Seeded aggregate types have dedicated commands with typed arguments:

LeftFold article create --title "ACL Recovery Timeline" --body @article.md --slug acl-recovery
LeftFold article list --status published --limit 10
LeftFold article publish <aggregate_id>
LeftFold image upload --file photo.jpg --alt-text "Clinic entrance"
LeftFold person create --name "Dr. Sarah Chen" --role "Senior Physiotherapist"

Dynamic aggregate types registered via event storming also produce typed commands. After registering a treatment aggregate:

LeftFold treatment create --name "ACL Rehabilitation" --duration-minutes 60
LeftFold treatment list

Agents

LeftFold agent list
LeftFold agent register --card agent-card.json
LeftFold agent card <agent_id>

Mailbox

LeftFold mailbox list --status pending
LeftFold mailbox get <task_id>
LeftFold mailbox approve <task_id>
LeftFold mailbox reject <task_id> --reason "Summary too long"
LeftFold mailbox edit <task_id> --artifact '{"summary":"Shorter summary"}'
LeftFold mailbox defer <task_id>
LeftFold mailbox ask <task_id> --message "Can you be more specific?"
LeftFold mailbox assign <task_id> --to-user <user_id>

Event storming

Define new aggregate types interactively by describing your domain:

LeftFold storming start --project <project_id>
LeftFold storming describe "I run a physio clinic with four practitioners..."
LeftFold storming proposals
LeftFold storming accept <proposal_id>
LeftFold storming reject <proposal_id>
LeftFold storming done

Output Formats

Every command supports three output modes:

Human (default)

Formatted tables with color-coded status badges:

$ LeftFold article list
ID          TITLE                    STATUS     UPDATED
a1b2c3d4    ACL Recovery Timeline    published  2h ago
e5f6g7h8    Rotator Cuff Guide       draft      1d ago

JSON

Machine-readable output for piping to jq or scripts. Use --json or -j.

LeftFold article list --json | jq '.[].title'

YAML

Human-readable structured output. Use --yaml or -y.

LeftFold article get a1b2c3d4 --yaml

Configuration

The config file lives at ~/.config/LeftFold/config.json:

~/.config/LeftFold/config.json

{
  "workspace": "acme",
  "api_key": "sk_...",
  "output": "human",
  "project": null
}

Field	Override	Description
workspace	--workspace, LEFTFOLD_WORKSPACE	Default workspace slug
api_key	--api-key, LEFTFOLD_API_KEY	Default API key
output	--json, --yaml, --human	Default output format
project	--project	Default project (scopes all commands)

Flags override env vars, which override the config file.

Pipeability

The CLI follows Unix conventions:

stdin: Commands that accept body content read from stdin when --body @- is passed
stdout: All output goes to stdout. Errors and progress messages go to stderr
Non-TTY: When stdin is not a terminal, commands run non-interactively — missing arguments produce errors, not prompts
Quiet mode: --quiet / -q suppresses all output except the result

cat article.md | LeftFold article create --title "My Article" --body @-

Exit Codes

Code	Meaning
0	Success
1	General error (invalid arguments, unknown command)
2	Authentication failure
3	Resource not found
4	Validation error (schema mismatch, missing fields)
5	Rate limited
10	Network error (cannot reach LeftFold API)

Example Workflows

Content creation

# Create an article from a markdown file
LeftFold article create \
  --title "ACL Recovery Timeline" \
  --body @acl-recovery.md \
  --slug acl-recovery \
  --tags sports,rehabilitation

# Agents enrich the article automatically — check what they produced
LeftFold mailbox list --status pending

# Review and approve the summary
LeftFold mailbox get t1 --json | jq '.artifacts[0].data.summary'
LeftFold mailbox approve t1

# Reject structured data and ask for revision
LeftFold mailbox reject t3 --reason "Missing author field"

# Publish
LeftFold article publish a1b2c3d4

Event storming

# Create a project and start event storming
LeftFold project create --name "Brisbane Physio" --slug brisbane-physio
LeftFold storming start --project brisbane-physio

# Describe the business in natural language
LeftFold storming describe \
  "I run a physiotherapy clinic with four physios. \
   We treat sports injuries and do post-surgical rehab."

# Review AI-generated aggregate proposals
LeftFold storming proposals --json

# Accept the ones you want, reject the rest
LeftFold storming accept p1
LeftFold storming accept p2
LeftFold storming reject p3
LeftFold storming done

# New aggregate types are immediately available
LeftFold treatment create --name "ACL Rehabilitation" --duration-minutes 60