Skip to main content
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 my 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

Register and manage tracked smart contracts

Segments

Create and manage user segments

Import

Import wallet addresses

​
Command Coverage

The CLI covers the main Formo API resources:
Command groupWhat you can do
formo profilesGet and search profiles, tune lifecycle thresholds, update properties, batch update properties with profiles properties batch, and manage labels
formo queryRun SQL against your Formo analytics data
formo analyticsRun pre-built KPI, funnel, retention, revenue, and top-N analytics pipes
formo eventsSend raw events with events ingest using a project SDK write key
formo boardsList, get, create, update, and delete dashboard boards
formo chartsList, get, create, update, query, move, duplicate, reorder, and delete charts
formo alertsList, get, create, update, test, toggle, and delete project alerts
formo contractsList, get, create, update, delete, inspect recommendations, and toggle pipeline inclusion
formo segmentsList, create, and delete user segments
formo importBulk 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.
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.
Get your API key from Settings → API Keys in the Formo dashboard.

​
Global commands

​
formo login

Authenticate with your Formo API key. Validates the key against the API and saves it locally.
ArgumentTypeRequiredDescription
apiKeystring❌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:
FieldDescription
apiKeyYour Formo API key
workspaceWorkspace name (set automatically on login)
projectIdProject ID (set automatically on login)

​
Environment Overrides

Environment variableDescription
FORMO_API_KEYWorkspace API key. Takes precedence over saved config.
FORMO_API_BASE_URLOverride the API base URL for local development or proxies.
FORMO_WRITE_KEYProject SDK write key for formo events ingest.
FORMO_EVENTS_BASE_URLOverride 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:
FlagDescription
--format <toon|json|yaml|md|jsonl>Output format (default: toon)
--jsonShorthand for --format json
--verboseInclude 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”
  • “search profiles ordered by last_onchain desc”
  • “set the display name and twitter handle on a wallet profile”
  • “batch update profile properties with profiles properties batch”
  • “tag a wallet as vip”
  • “batch upsert labels for wallets”
  • “remove a label from a wallet profile”
  • “list all project alerts”
  • “create an alert for high-value transactions”
  • “send a test alert”
  • “list all dashboard boards”
  • “create a dashboard board”
  • “list charts in a board”
  • “create a line chart in a board”
  • “move a chart to another board”
  • “duplicate a chart”
  • “list all tracked contracts”
  • “register a new smart contract”
  • “toggle contract pipeline inclusion”
  • “list user segments”
  • “import wallet addresses”
  • “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