CLI Commands

Complete reference for all Buddhi CLI commands.

buddhi login

Authenticate with an agent key and store credentials locally.

Usage

buddhi login [--key crtx_...] [--url https://your-buddhi-host]

Flags

Flag	Description
`--key`	Agent key (or use `BUDDHI_API_KEY` env)
`--url`	Buddhi AI endpoint (or use `BUDDHI_URL` env, default: `http://localhost:4040`)

--url defaults to http://localhost:4040. If your Buddhi AI runs anywhere else (a deployed host), omitting --url makes login fail with Verifying with Buddhi AI… ✗ fetch failed — it's trying to reach a local server that isn't there. The onboarding screen fills in the correct --url for you automatically.

Interactive Mode

If --key is not provided, you'll be prompted:

Paste your Buddhi API key (crtx_...):

Examples

# Login with flags
buddhi login --key crtx_abc123 --url https://buddhi.example.com

# Login with env vars
export BUDDHI_API_KEY="crtx_abc123"
export BUDDHI_URL="https://buddhi.example.com"
buddhi login

# Interactive login
buddhi login

Output

Verifying with Buddhi AI… done.
✓ Logged in as John Doe <john@company.com> — role IC.
  Credentials saved to /Users/john/.buddhi/config.json

buddhi whoami

Show the currently authenticated identity.

Usage

buddhi whoami

Output

John Doe <john@company.com> — role IC, level Senior
Endpoint: https://buddhi.example.com

buddhi push

Push a file as a memory into Buddhi AI.

Usage

buddhi push <file> [--title "..."] [--scope engineering]

Flags

Flag	Description
`--title`	Human-readable title (defaults to filename)
`--scope`	Scope key to write into (e.g., `engineering`)

Examples

# Push a markdown file
buddhi push ./api-design.md --title "API Design Guidelines" --scope engineering

# Push with default title (filename)
buddhi push ./notes.txt --scope public-docs

# Push without scope (uses source-based default)
buddhi push ./decision.md

Output

✓ Pushed memory a1b2c3d4-e5f6-7890-abcd-ef1234567890

Error Cases

Error	Cause
`Not logged in`	Run `buddhi login` first
`Verifying with Buddhi AI… fetch failed`	Wrong `--url` — the CLI can't reach the host. Pass `--url https://your-buddhi-host`
`File not found`	Check the file path
`push failed: scope denied`	Your role can't write to this scope

Environment Variables

Variable	Description	Overrides
`BUDDHI_API_KEY`	Agent key	`--key` flag
`BUDDHI_URL`	Buddhi AI endpoint	`--url` flag

Credential Storage

Credentials are stored at ~/.buddhi/config.json:

{
  "apiKey": "crtx_...",
  "url": "https://buddhi.example.com",
  "actingUser": {
    "name": "John Doe",
    "email": "john@company.com",
    "role": "IC",
    "level": "Senior"
  }
}

The config file is created with mode 600 (owner read/write only). Do not share your agent key.