@frontline/cli

Unified Frontline command-line toolbox. Ships two binaries:

• frontline — public REST API: agents, workflows, billing, tables, objects, raw GET, Claude Code skills setup.
• max — Max chat & admin REST (per-user API key as Bearer, interactive chat).

Note (dev): the default base URL is http://localhost:7010/public/v1. When deploying to production, update it manually (per-profile, flag, or env var).

Installation

npm install -g @frontline-ai/cli

Or run without installing:

npx @frontline-ai/cli --help

Output format

All frontline commands print JSON to stdout by default so you can pipe them into jq, scripts, or CI. Opt into human-readable output with:

• --pretty — key/value blocks, spinners, icons (to stderr-safe channels)
• --table — tabular rendering for list endpoints

Errors always go to stderr in human form and to stdout as structured JSON when the command was invoked in its default (non-pretty) mode.

frontline binary

Authentication

API keys are sent via Authorization: Bearer.

Login

# Default profile, default base URL (localhost in dev)
frontline auth login <api-key>

# Multiple environments via named profiles
frontline auth login <key> --profile production --base-url https://api.getfrontline.ai/public/v1
frontline auth login <key> --profile staging    --base-url https://staging-api.example.com/public/v1

The key is stored locally in your OS config dir (via conf). No /me//billing verification is performed at login time — the key is saved as-is and validated on first real call.

Switch / inspect profiles

frontline auth profiles list      # all saved profiles + active one
frontline auth profiles use prod  # change active profile
frontline auth whoami             # hits /me with current profile
frontline auth logout             # remove active profile
frontline auth logout --profile staging

Resolution priority

--api-key / --base-url flags → FRONTLINE_API_KEY / FRONTLINE_BASE_URL env → active profile → default (http://localhost:7010/public/v1).

Commands

Agents

frontline agents list
frontline agents list --status active
frontline agents flows <agentId>
frontline agents flows <agentId> --status active
frontline agents analytics <agentId> --start-date 2025-01-01 --end-date 2025-12-31

Workflows

frontline workflows list
frontline workflows list --status active
frontline workflows analytics <workflowId> --start-date 2025-01-01 --end-date 2025-12-31

Billing

frontline billing get

Raw API requests

For endpoints not yet mapped to a command:

frontline api get /agents
frontline api get /agents --query status=active
frontline api get /workflows/123/analytics --query startDate=2025-01-01 endDate=2025-12-31

Objects (CRM entities)

frontline object list
frontline object get sor__people
frontline object schema sor__deals
frontline object create --data '{"name":"custom_obj","displayName":"Custom","fields":[...]}'
frontline object update sor__deals --data '{"displayName":"Deals v2"}'
frontline object count sor__deals
frontline object delete sor__custom_object

Tables (spreadsheet-like)

frontline table list
frontline table get my_table
frontline table create my_table --data '{"displayName":"My Table","columns":[{"name":"Name","type":"string","metadata":{"format":"text"}}]}'
frontline table delete my_table

Shared sub-commands (object & table)

Both object and table expose the same set of sub-commands:

| Command | Description | | ---------------- | ----------------------------------------------- | | field | Manage fields (columns) — CRUD | | option | Manage select-field options — CRUD | | record / row | Manage rows — list, get, create, update, delete | | relation | Link / unlink related records | | view | Manage views (object only) — CRUD | | record-type | Manage record types (object only) | | note | Notes on rows — CRUD | | task | Tasks on rows — CRUD + complete / uncomplete | | file | Files on rows — list, get, download, delete | | aggregation | Aggregations — CRUD + compute | | export | Export data as XLSX or CSV |

Run frontline <resource> <subcommand> --help for details and examples.

Global flags

Every frontline command accepts:

• --api-key <key> — override stored API key for a single call
• --base-url <url> — override stored base URL for a single call
• --profile <name> — use a specific saved profile
• --debug — verbose request/response logs (token is redacted)
• --pretty — human-readable output
• --table — tabular output for list endpoints

Claude Code Skills

Install Frontline skills into Claude Code (auto-detected on npm install):

frontline setup --claude-skills          # install new skills
frontline setup --claude-skills --force  # overwrite existing

Skills currently shipped:

• Public API: frontline-agents, frontline-workflows, frontline-billing, frontline-api
• Max: max-chat, max-auth
• Table / Object CRUD: auth-and-profiles, crm-setup, crud-operations, pipeline-setup, schema-design, resource-creation, record-type-management, relations, filter-and-query, files, notes-and-tasks, export-and-delete, aggregations

Debugging

frontline agents list --debug

Troubleshooting

• "No API key found" — run frontline auth login <key> or set FRONTLINE_API_KEY.
• "No Max API key found" (Max CLI) — run max auth login <key> or frontline auth login <key> on the same profile, or set MAX_API_KEY / FRONTLINE_API_KEY.
• "Missing or invalid API key" — key expired / revoked. Generate a new one.
• "Request timed out" — check network; if using a custom base URL, verify with frontline auth profiles list.
• Rate limit — public API allows 100 req/min.

max binary

Authentication uses the same per-user API key as the Public API (frontline). Running max auth login <api-key> saves the key to both the Max store (max-cli) and the Frontline store (frontline-cli) under the same profile name, so max and frontline commands stay in sync.

Browser SSO (Firebase) is paused. The old hosted-login flow is commented out in the CLI; the implementation remains in the repo (packages/cli/src/max/browserLogin.ts) for when SSO is re-enabled.

max --help
max auth login <api-key>
max auth login <api-key> --profile staging --base-url https://.../public/v1
max auth whoami
max auth logout                    # clears Max + matching Frontline profile
max auth logout --keep-frontline   # only clears the Max store

API key resolution (Max commands)

--api-key → MAX_API_KEY or FRONTLINE_API_KEY → Max profile apiKey → Frontline profile apiKey (same profile name).

Response shape and stdout

Max Public API responses are typically { "ok": true|false, "data": ... }. HTTP errors still use 4xx/5xx; logical failures may return 200 with ok: false (the CLI treats those as errors).

• max "…" (root) and max chat send: default stdout is one-line JSON (JSON.stringify of the last response: POST, or last GET after polling). Use --pretty for assistant plain text from data. Use --json to print only the POST body and skip polling.
• max conversations …: same idea — default one-line JSON; --pretty for plain text when the CLI can infer it.
• max chat / REPL: stdout is assistant plain text from data when possible (interactive UX); otherwise one-line JSON. No progress spinners on stdout.

Public API — Max conversations

Base URL is the same as frontline (must end with /public/v1). Routes:

| Method | Path (after base) | | ------- | ------------------------------------------------- | | POST | /max/conversations/message | | GET | /max/conversations/:conversationId | | PATCH | /max/conversations/:conversationId | | POST | /max/conversations/:conversationId/abortMessage | | GET | /max/conversations/ |

CLI:

max conversations list
max conversations get 123
max conversations update 123 --data '{"title":"Renamed"}'
max conversations abort 123
# alias: max conv list

Global flags: --profile, --base-url, --api-key, --pretty, --debug (same resolution as max chat send).

Chat with Max

After max auth login, you can send messages:

# Send message (uses last conversation by default)
max "Hola"

# Start a new conversation
max --new "Hola"

# Explicit conversation id
max --conversation 123 "Hola"

# Default: one-line JSON from the API; human reply with --pretty
max "Hola" --pretty

# Override API key or Public API base for one run
max "Hola" --api-key flk_...
max chat send "Hola" --base-url https://localhost:7010/public/v1

# Alternative explicit command form
max chat send "Hola"

You can also start an interactive session (so you don't have to type max every time):

max chat

Inside the interactive prompt, use:

• :help for commands
• :new to start a new conversation
• :conv <id> to switch conversations
• :exit to quit

Configuration

Max uses the Frontline Public API host (same as frontline: profile baseUrl, FRONTLINE_BASE_URL, or built-in default — typically .../public/v1).

export FRONTLINE_BASE_URL="https://localhost:7010/public/v1"
max --new "Hola" --debug

--api-base-url on older docs is a deprecated alias for --base-url (Public API root only).

Terminal logo (optional)

The package ships a bundled logo at packages/cli/assets/logo3.png (included in the published npm package via package.json → files). The CLI looks for it automatically.

Override the path:

export MAX_CLI_LOGO_PATH="/absolute/path/to/logo3.png"

If the logo can't be rendered (many Windows terminals), the CLI still shows the text welcome banner.

Config file location

max config-path

Development

This package lives inside the monorepo at packages/cli.

cd packages/cli
npm install
npm run dev:frontline -- agents list   # run frontline without building
npm run dev:max -- "Hola"              # run max without building
npm run build                          # compile TypeScript to dist/
node dist/index.js --help              # run compiled frontline
node dist/max.js --help                # run compiled max

Config is persisted via conf:

• frontline binary → project name frontline-cli
• max binary → project name max-cli

They use separate config files, but max auth login <api-key> writes the same API key (and optional --base-url for Frontline) to both stores under the same profile name. If you only run frontline auth login, Max commands can still read that key from the Frontline profile (same profile name) as a fallback.