FLock Agent Docs

CLI & API Reference

Sign In

Quick Start — Install CLI and Go

Install the @flock-io/api CLI from npm and start operating the platform in 3 commands:

$ npm install -g @flock-io/api

$ flock auth login --email you@yourorg.com --password '...' --json

$ flock models list --json

Sign up at platform.flock.io to get your account and API key. Full reference below.

FLock Model API Platform — Agent Skill

Everything an AI agent needs to operate FLock. Install the CLI, authenticate, start calling.

npm install -g @flock-io/api

Production Endpoints:

ServiceURLAuth
LLM Inference (OpenAI-compatible)https://api.flock.io/v1x-litellm-api-key: sk-...
Platform Management APIhttps://platform.flock.io/apiAuthorization: Bearer <jwt>
Platform UI (signup, dashboard)https://platform.flock.ioBrowser
This skill file (raw)https://platform.flock.io/api/agents/skillNone
npm package@flock-io/apiNone

1. Quick Start (4 commands)

# Install
npm install -g @flock-io/api

# Authenticate
flock auth login --email you@yourorg.com --password '...'

# Browse models
flock models list --json

# Call an LLM (requires a platform API key from the dashboard)
flock chat --model qwen3-30b-a3b-instruct-2507 --api-key sk-your-key "Hello!" --json

Don't have an account? Sign up at platform.flock.io, create a team, create an API key, and purchase credits. See Getting Started.

2. Two APIs — Know the Difference

APIBase URLAuthUse For
LLM Inferencehttps://api.flock.io/v1x-litellm-api-key: sk-...Chat completions, image generation (OpenAI-compatible)
Platform Managementhttps://platform.flock.io/apiAuthorization: Bearer <jwt>Account, API keys, teams, billing, usage logs

The flock CLI talks to the Platform Management API. For LLM inference, use your API key directly with api.flock.io/v1 or via flock chat.

3. CLI Reference

3.1 Configuration

# Default points to https://platform.flock.io — override if needed:
flock config set api-url https://platform.flock.io
flock config show --json
Env VariablePurposeDefault
FLOCK_API_BASE_URLPlatform base URLhttps://platform.flock.io
FLOCK_API_TOKENBearer JWT (skips login)—
FLOCK_LLM_API_KEYDefault API key for flock chat—

Credentials stored in ~/.flock/credentials.json (mode 0600).

3.2 Auth

# Sign in (non-interactive, agent-friendly)
flock auth login --email you@yourorg.com --password '...' --json
# → { "token": "eyJ...", "expiresAt": "...", "email": "..." }

# Or skip login entirely with env vars:
export FLOCK_API_TOKEN="eyJ..."

# Check who you are
flock auth whoami --json
# → { "user": { "id": 1, "email": "...", "name": "...", "role": "user" } }

# Print raw token (for piping)
flock auth token

# Sign out
flock auth logout

3.3 Models

# List all models
flock models list --json

# Search and filter
flock models list --search qwen --type chat --json

# Get a specific model
flock models get <model-id> --json

# List providers
flock models providers --json

3.4 API Keys

# List your keys
flock api-keys list --json

# Create a key (requires team ID)
flock api-keys create --name "my-agent" --team-id <team-id> --json

# Rename a key
flock api-keys update --token sk-... --name "renamed" --json

# Delete a key
flock api-keys remove --token sk-...

3.5 Organizations

Organizations are auto-created when you sign up. Use the CLI to list and inspect them.

# List orgs
flock orgs list --json

# List members
flock orgs members --org-id <org-id> --json

3.6 Teams

# List teams
flock teams list --json

# Create team (uses your active org; --org-id is passed to the CLI but org is resolved from session)
flock teams create --name "Engineering" --org-id <org-id> --json

# Get team details
flock teams get <team-id> --json

# Invite a member
flock teams invite --team-id <team-id> --email dev@yourorg.com --role member

# Remove a member
flock teams remove-member --team-id <team-id> --user-id <user-id>

3.7 Billing & Usage

# Check credit balance (amount in nano-USD; divide by 1e9 for USD)
flock balance --json

# Query usage logs
flock usage --start-date 2026-04-01 --end-date 2026-04-07 --json

# Filter by API key
flock usage --api-key sk-... --json

3.8 Chat (LLM Completion)

# Basic completion
flock chat --model qwen3-30b-a3b-instruct-2507 --api-key sk-... "What is 2+2?" --json
# → { "content": "2 + 2 equals 4." }

# Stream to stdout
flock chat --model qwen3-30b-a3b-instruct-2507 --api-key sk-... "Write a haiku" --stream

# Use env var for API key
export FLOCK_LLM_API_KEY="sk-..."
flock chat --model qwen3-30b-a3b-instruct-2507 "Hello!" --json

3.9 Admin (admin role only)

flock admin users list --page 1 --json
flock admin users get <id> --json
flock admin users delete <id>
flock admin models create --name "Model" --provider qwen --litellm-id my-model --json

3.10 REPL

Run flock with no arguments to enter an interactive REPL:

$ flock
flock> models list --json
flock> balance --json
flock> exit

4. Direct HTTP API (Alternative to CLI)

All CLI commands map to HTTP calls. Use these when the CLI is not available.

4.1 Get a Bearer Token

curl -s -X POST 'https://platform.flock.io/api/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@yourorg.com","password":"your-password"}'
# → { "token": "eyJ...", "expiresAt": "..." }

4.2 Use the Token

TOKEN="eyJ..."
curl -s 'https://platform.flock.io/api/models' -H "Authorization: Bearer $TOKEN"
curl -s 'https://platform.flock.io/api/api-keys' -H "Authorization: Bearer $TOKEN"
curl -s 'https://platform.flock.io/api/balance' -H "Authorization: Bearer $TOKEN"

4.3 Call the LLM API Directly

curl -X POST 'https://api.flock.io/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'x-litellm-api-key: sk-your-api-key' \
  -d '{
    "model": "qwen3-30b-a3b-instruct-2507",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Or use the OpenAI Python SDK:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.flock.io/v1",
    api_key="sk-your-api-key",
)

response = client.chat.completions.create(
    model="qwen3-30b-a3b-instruct-2507",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

4.4 Full HTTP Endpoint Table

MethodPathAuthDescription
POST/api/auth/tokenNoneExchange credentials for JWT
POST/api/auth/token/refreshBearerRefresh JWT
GET/api/auth/meBearerCurrent user
GET/api/modelsNoneList models
GET/api/providersNoneList providers
GET/api/api-keysBearerList keys
POST/api/lite-llm/api-keysBearerCreate key { name, team_id }
POST/api/api-keys/updateBearerUpdate key { token, name }
POST/api/api-keys/removeBearerDelete key { apiKey }
GET/api/lite-llm/organizations/listBearerList orgs
PUT/api/lite-llm/organizationsBearerUpdate org
GET/api/lite-llm/teamsBearerList teams
POST/api/lite-llm/teamsBearerCreate team { name } (uses active org from session)
GET/api/lite-llm/teams/:idBearerGet team
POST/api/lite-llm/teams/invite-memberBearerInvite { teamId, teamName, email, role }
POST/api/lite-llm/teams/remove-memberBearerRemove { teamId, memberId }
GET/api/balanceBearerCredit balance
GET/api/quotaBearerQuota details
GET/api/lite-llm/logsBearerUsage logs
POST/api/lite-llm/messagesBearerChat completion (platform proxy) { model, messages, apiKey }

LLM Inference (separate API, OpenAI-compatible):

MethodPath (base: api.flock.io/v1)Auth HeaderDescription
POST/chat/completionsx-litellm-api-keyDirect chat completion

5. Response Formats

Success (paginated)

{ "data": [...], "meta": { "page": 1, "pageSize": 10, "total": 42, "totalPages": 5 } }

Error

{ "error": "Human-readable message", "code": "MACHINE_CODE" }

Codes: UNAUTHORIZED, FORBIDDEN, VALIDATION_ERROR, NOT_FOUND, QUOTA_EXCEEDED, TEAM_BLOCKED, SERVER_ERROR, DB_TIMEOUT.

CLI Error (with --json)

{ "error": "Not logged in", "code": "UNAUTHORIZED", "status": 401 }

Without --json: red line to stderr, exit code 1.

6. Common Agent Workflows

A: Get started from zero

npm install -g @flock-io/api
flock auth login --email you@yourorg.com --password '...' --json
flock orgs list --json                                       # note your org ID
flock teams create --name "Agents" --org-id <org_id> --json  # note team ID
flock api-keys create --name "bot" --team-id <team_id> --json # note the key
flock chat --model qwen3-30b-a3b-instruct-2507 --api-key <key> "Hello!" --json

B: Check billing

flock balance --json
flock usage --start-date 2026-04-01 --end-date 2026-04-07 --json

C: Rotate an API key

flock api-keys list --json
flock api-keys remove --token <old>
flock api-keys create --name "rotated" --team-id <team_id> --json

D: Environment-only auth

export FLOCK_API_TOKEN="eyJ..."
flock models list --json
flock balance --json

7. Domain Concepts

Entity Hierarchy

User → Organization → Team → APIKey → calls api.flock.io/v1
                    → OrganizationQuota (nano-USD balance)

Currency

nano-USD: 1 USD = 1,000,000,000 nano-USD. Divide amount by 1e9 for USD.

Credit Lifecycle

Sign up → buy credits → create API key → call LLM → usage settled → quota decreases → negative = teams blocked → buy more = unblocked.

8. Troubleshooting

SymptomFix
401 on api.flock.ioUse x-litellm-api-key: sk-... not Authorization: Bearer
401 on CLI commandsflock auth login or set FLOCK_API_TOKEN
QUOTA_EXCEEDED / TEAM_BLOCKEDBuy credits at platform.flock.io > Settings > Billing
Model not foundflock models list --json to see available models
403 on admin commandsRequires admin role

9. Links