CLI overview - Formo Docs

The Formo CLI (@formo/cli) gives you full access to the Formo API from the command line. Use it interactively in your terminal, in shell scripts, or as a tool for AI agents.

Profiles

Fetch, search, and update wallet profiles and labels

Query

Run SQL queries on your data

Analytics

Run pre-built analytics pipes (KPIs, funnels, retention, revenue)

Events

Send raw analytics events with a project SDK write key

Boards

Create and manage dashboard boards

Charts

Create and manage charts within custom dashboards

Alerts

Configure project alerts

Contracts

Segments

Create and manage user segments

Import

Import wallet addresses

Command Coverage

The CLI covers the main Formo API resources:

Command group	What you can do
`formo profiles`	Get and search profiles, tune lifecycle thresholds, update properties, batch update properties with `profiles properties batch`, and manage labels
`formo query`	Run SQL against your Formo analytics data
`formo analytics`	Run pre-built KPI, funnel, retention, revenue, and top-N analytics pipes
`formo events`	Send raw events with `events ingest` using a project SDK write key
`formo boards`	List, get, create, update, and delete dashboard boards
`formo charts`	List, get, create, update, query, move, duplicate, reorder, and delete charts
`formo alerts`	List, get, create, update, toggle, and delete project alerts
`formo contracts`	List, get, create, update, and delete tracked contracts (pipeline inclusion via `update --include-in-pipeline`)
`formo segments`	List, create, and delete user segments
`formo import`	Bulk import wallet addresses, optionally with profile properties

Installation

Install the CLI globally via npm:

npm install -g @formo/cli

Or run without installing using npx:

npx @formo/cli

Quick start

# 1. Authenticate with your API key
formo login formo_abc123

# 2. Get a wallet profile
formo profiles get vitalik.eth

# 3. Run a SQL query
formo query run "SELECT count(*) FROM events"

# 4. List your dashboard boards
formo boards list

# 5. Send a raw event with a project SDK write key
FORMO_WRITE_KEY=formo_write_key_xxx formo events ingest \
  --event '{"type":"track","channel":"cli","version":"1","anonymous_id":"anon_123","event":"CLI Test","context":{},"properties":{},"original_timestamp":"2026-04-27T23:05:38.000Z","sent_at":"2026-04-27T23:05:42.000Z","message_id":"cli-test-1"}'

Authentication

The CLI supports two authentication methods. The environment variable takes precedence over the saved config file.

Login command
Environment variable

Save your API key to the local config file (~/.config/formo/config.json):

formo login formo_abc123

The CLI validates your key against the API, saves the key along with your workspace and project info, and confirms that you’re authenticated.

Set the FORMO_API_KEY environment variable:

export FORMO_API_KEY=formo_abc123

This takes precedence over a saved config file and is useful for CI/CD pipelines and scripts.

Get your API key from Settings → API in the Formo dashboard.

Global commands

Authenticate with your Formo API key. Validates the key against the API and saves it locally.

Argument	Type	Required	Description
`apiKey`	`string`	❌	Your `formo_` API key (shows a setup guide if omitted)

formo login formo_abc123

`formo logout`

Remove saved API key and clear authentication from ~/.config/formo/config.json.

formo logout

If the FORMO_API_KEY environment variable is set, logout will warn you to also run unset FORMO_API_KEY.

`formo status`

Show the current authentication and CLI status, including the active API key source, workspace, and project ID.

formo status

Output includes:

Whether you are authenticated
API key source (config file or FORMO_API_KEY env var)
Workspace name
Project ID

Configuration

The CLI stores configuration at ~/.config/formo/config.json with restricted permissions (600). The config file contains:

Field	Description
`apiKey`	Your Formo API key
`workspace`	Workspace name (set automatically on login)
`projectId`	Project ID (set automatically on login)

Environment Overrides

Environment variable	Description
`FORMO_API_KEY`	Workspace API key. Takes precedence over saved config.
`FORMO_API_BASE_URL`	Override the API base URL for local development or proxies.
`FORMO_WRITE_KEY`	Project SDK write key for `formo events ingest`.
`FORMO_EVENTS_BASE_URL`	Override the events API base URL for local development or proxies.

Output format

By default, commands print compact, human-readable TOON output. Pass one of the standard output flags to change the format:

Flag	Description
`--format <toon\|json\|yaml\|md\|jsonl>`	Output format (default: `toon`)
`--json`	Shorthand for `--format json`
`--verbose`	Include the full response envelope (`ok`, `data`, `meta`)
`--filter-output <keys>`	Filter output by key paths (e.g. `data,meta.duration`)

Status messages (login confirmation, errors, and similar) are written to stderr in interactive terminals, so they never pollute piped output.

# Default TOON output
formo profiles get vitalik.eth

# JSON output, piped to jq
formo profiles get vitalik.eth --json | jq '.net_worth_usd'

AI agent usage

The CLI is designed to work as a tool for AI agents. It includes built-in suggestions for natural language queries:

“get the profile for wallet 0xabc”
“search profiles with net worth > 10000”
“run a SQL query on my analytics data”
“show traffic KPIs for the last 7 days”
“get the conversion funnel for the last month”
“list the top wallets by activity”
“search profiles ordered by last_onchain desc”
“list all project alerts”
“create an alert for high-value transactions”
“list charts in a board”
“create a line chart in a board”
“move or duplicate a dashboard chart”
“list all tracked contracts”
“register a new smart contract”
“list user segments”
“import wallet addresses”
“batch update profile properties with profiles properties batch”
“batch upsert labels for wallets”
“send raw analytics events”

Agent Integrations

The CLI is built with incur, so agents can discover and call commands through structured metadata:

# Print an LLM-readable command manifest
formo --llms

# Register the CLI as an MCP server
formo mcp add

# Start an MCP stdio server directly
formo --mcp

# Sync Formo CLI skill files for compatible agents
formo skills add

Profiles

Query

Analytics

Events

Boards

Charts

Alerts

Contracts

Segments

Import

​Command Coverage

​Installation

​Quick start

​Authentication

​Global commands

​formo login

​formo logout

​formo status

​Configuration

​Environment Overrides

​Output format

​AI agent usage

​Agent Integrations

Command Coverage

Installation

Quick start

Authentication

Global commands

`formo login`

`formo logout`

`formo status`

Configuration

Environment Overrides

Output format

AI agent usage

Agent Integrations