AgentBrain CLI

TypeScript command-line tool for interacting with the AgentBrain enterprise data hub API.

Full-coverage admin CLI: manage organizations, connectors, knowledge bases, documents/media, workflows, the knowledge graph, permissions, LLM/prompt config, cost & usage, audit logs, and system settings — all from the terminal. It covers the same backend surface as the AgentBrain MCP server plus the broader CMS admin API.

Installation

Install via npm:

npm install -g agentbrain

Or with pnpm:

pnpm add -g agentbrain

Requires Node 20+.

Authentication model

AgentBrain uses two credentials depending on which surface you call:

| Surface | Commands | Credential | | --- | --- | --- | | Admin / CMS (default) | Almost everything | Bearer JWT — config key token | | MCP surface | retrieve-context, connector query, connector execute, governance ai-policy | API key — config key apiKey |

Every request also sends your organization ID (orgId) as the X-Org-Id header.

Breaking change (upgrading from an apiKey-only setup): admin/CMS commands now require a bearer token (token), not the API key. The API key still authenticates the MCP-surface commands listed above. If you previously configured only apiKey, set token as well.

The bearer JWT is short-lived, so instead of pasting it manually use the auth command group:

agentbrain auth login                        # prompts email + password (hidden)
agentbrain auth login --email [email protected]
agentbrain auth status                       # verify who you're logged in as
agentbrain auth logout                       # revoke + clear stored tokens

auth login authenticates against the Builder Auth service — a separate service from the hub apiUrl — and stores both the access token (as token) and the refresh token (as refreshToken) in ~/.agentbrain/config.json (mode 0600). It needs two settings, resolvable from config, env, or flags:

• authUrl — Builder Auth base URL (defaults to the cloud auth service; --auth-url / AGENTBRAIN_AUTH_URL to override)
• tenantId — your deployment's tenant ID (--tenant / AGENTBRAIN_TENANT_ID; prompted if unset)

Silent refresh: once you're logged in, admin commands will silently refresh the access token via /v1/auth/refresh when they hit a 401, retry once, and write the rotated pair back to your config. You should not need to re-run auth login until the refresh token itself expires. Username-based deployments use agentbrain auth login --username <name>.

Quick Start

Option 1: Interactive Setup (Recommended)

agentbrain config init

The wizard prompts for API URL, a bearer token (JWT, for admin/CMS commands), an optional API key (only for MCP-surface commands), and a default organization ID. Choose cloud https://api.agentbrain.sh or a custom on-premise URL.

Option 2: Manual Configuration

# Admin/CMS surface (most commands): bearer JWT
agentbrain config set token <your-jwt>
agentbrain config set apiUrl https://api.agentbrain.sh
agentbrain config set orgId org_xxxxx

# MCP surface (only for `agentbrain mcp *`): API key
agentbrain config set apiKey sk_live_xxxxx

Verify Setup

agentbrain me get

Uploading documents & media

Upload runs the AgentBrain 3-step flow automatically: presign → PUT the raw bytes to storage → commit. Kind (raw_doc/image/audio/video) and content-type are auto-detected from the file extension; a client-side sha256 is computed for integrity (auto-skipped for very large files). Max size 500MB.

# Upload a document (auto-detects kind/content-type)
agentbrain media upload ./report.pdf

# Upload into a folder, overriding kind/content-type
agentbrain media upload ./notes.txt --folder-id fld_xxx --kind raw_doc --content-type text/plain

# Skip client-side sha256 (e.g. for large files)
agentbrain media upload ./big-video.mp4 --no-sha256

# Manage uploaded assets
agentbrain media list --folder-id fld_xxx --kind raw_doc
agentbrain media get <id>
agentbrain media update <id> --file-name "renamed.pdf" --folder-id fld_yyy
agentbrain media download-url <id>        # presigned GET URL
agentbrain media preview <id>             # structured preview
agentbrain media transcribe <id>          # audio/video transcription
agentbrain media delete <id>
agentbrain media bulk-delete --ids id1,id2,id3

Usage

The CLI groups commands by domain. Run agentbrain --help for the full list, or agentbrain <group> --help for a group.

Organizations

agentbrain org list
agentbrain org get <id>
agentbrain org create --name "Acme Corp" --type "enterprise"
agentbrain org switch org_xxxxx

# Members
agentbrain org members <id>
agentbrain org add-member <orgId> --user-id user_xxxxx --role admin
agentbrain org update-member-role <orgId> <memberId> --role admin
agentbrain org remove-member <orgId> <memberId>

Connectors

agentbrain connector list
agentbrain connector get <id>
agentbrain connector create --name "PostgreSQL" --type postgres --subtype standard
agentbrain connector test <id> --config '{...}'

# Inspect data sources
agentbrain connector databases <id>
agentbrain connector schemas <id> --database mydb
agentbrain connector tables <id> --database mydb --schema public

# Sharing (share with a user, then optionally revoke)
agentbrain connector share create <id> --user-id user_xxxxx --permission read
agentbrain connector share list <id>
agentbrain connector share delete <id> <userId>

Knowledge Bases

agentbrain knowledge list
agentbrain knowledge get <id>
agentbrain knowledge by-slug <slug>
agentbrain knowledge create --title "Product Docs"

# Publishing & relationships
agentbrain knowledge publish <id>
agentbrain knowledge unpublish <id>
agentbrain knowledge related <id>

# Versions
agentbrain knowledge versions <id>
agentbrain knowledge version <id> <versionId>
agentbrain knowledge rollback <id> <versionId>

# Public share link
agentbrain knowledge share <id> --expires-in 86400 --max-access-count 50

Documents & Media

See Uploading documents & media above, plus background jobs and org media settings:

agentbrain media job list
agentbrain media settings get

Workflows

agentbrain workflow list
agentbrain workflow create --name "ETL Job" --cron "0 0 * * *"

# Steps
agentbrain workflow steps list <id>
agentbrain workflow steps create <id> --step-type transform --step-name "clean" --step-order 1

# Execute and monitor
agentbrain workflow run <id>
agentbrain workflow runs <id>
agentbrain workflow logs <id> <runId>
agentbrain workflow cancel <id> <runId>

Knowledge Graph

agentbrain kg entity list
agentbrain kg relation list
agentbrain kg graph summary --include-orphaned     # also: top | community <id> | neighbors <entityId>
agentbrain kg extraction status
agentbrain kg taxonomy list

Permissions

agentbrain permission-group list                 # alias: pg
agentbrain permission-group create --name "Analysts"
agentbrain permission-group users <groupId>
agentbrain permission-group table-perm list <groupId>

# Resource-level checks (current user)
agentbrain permission check --resource-type connector --resource-id conn_xxx --action read

# Verify the effective table-ACL decision (top-level command)
agentbrain verify-permission \
  --connector-id conn_xxx --table-pattern "payments.*" --action can_select

Other Command Groups

agentbrain category list                 # + category tree
agentbrain folder list
agentbrain tag list
agentbrain search --query "my-connector"
agentbrain query-log list
agentbrain llm provider list             # LLM provider config
agentbrain prompt template list          # prompt templates
agentbrain cost budget get               # cost budget & spend
agentbrain usage metrics summary         # usage metrics
agentbrain dashboard summary             # dashboard aggregates
agentbrain audit list                    # audit logs
agentbrain system health                 # platform system status
agentbrain retrieve-context --question "..."   # MCP context retrieval (uses apiKey)

Configuration

Config stored at ~/.agentbrain/config.json (mode 0600 for security).

Resolution order (highest to lowest priority):

1. CLI flags (--token, --api-key, --api-url, --org, --output)
2. Environment variables (AGENTBRAIN_TOKEN, AGENTBRAIN_API_KEY, AGENTBRAIN_API_URL, …)
3. Config file (~/.agentbrain/config.json)
4. Defaults

View / edit config:

agentbrain config list          # secrets (token, apiKey) are masked
agentbrain config get token
agentbrain config set timeout 60000

Supported config keys:

• apiUrl — API endpoint (default: https://api.agentbrain.sh)
• token — bearer JWT for admin/CMS commands (set automatically by agentbrain auth login; masked in config list)
• refreshToken — refresh token for silent access-token rotation (set automatically by auth login; masked in config list)
• apiKey — API key for MCP-surface commands (retrieve-context, connector query/execute, governance ai-policy)
• orgId — default organization ID
• authUrl — Builder Auth service base URL used by auth login and silent refresh (default: cloud auth service)
• tenantId — Builder Auth tenant ID used by auth login and silent refresh
• output — output format: json, table, yaml (default: table for TTY, json for pipes)
• timeout — request timeout in ms (default: 30000)

Output Formats

Default behavior:

• TTY (interactive terminal) → table format (colored, human-readable)
• Pipe/redirect → json format (machine-readable)

Override with --output:

agentbrain org list --output json
agentbrain org list --output yaml
agentbrain org list --output table

Global Options

All commands support:

--api-url <url>      Override API endpoint
--token <jwt>        Override bearer token (admin/CMS)
--api-key <key>      Override API key (mcp)
--org <id>           Override organization ID
--output <fmt>       Output format: json, table, yaml
--verbose            Enable request logging (presigned URL signatures are redacted)

Error Handling

Errors include the HTTP status code, the API error message, and full response data in verbose mode (--verbose).

agentbrain org get invalid-id 2>&1
# Error 404: Organization not found

Development

git clone https://github.com/nextlevelbuilder/agentbrain-cli
cd agentbrain-cli
pnpm install
pnpm build
pnpm test

Dev mode with watch:

pnpm dev

License

MIT