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 and search wallet profiles

Query

Run SQL queries on analytics data

Boards

Manage dashboard boards

Charts

Create and manage charts within boards

Alerts

Configure project alerts

Contracts

Register and manage tracked smart contracts

Segments

Create and manage audience segments

Import

Bulk import wallet addresses

​
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 "SELECT count(*) FROM events"

# 4. List your dashboard boards
formo boards list

​
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)

​
Output format

  • Interactive mode (TTY): The CLI displays colored, human-readable output with status icons and formatting.
  • Piped/scripted mode: The CLI outputs raw JSON, making it easy to pipe into jq or other tools.
# Human-friendly output
formo profiles get vitalik.eth

# Pipe JSON to jq
formo profiles get vitalik.eth | 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”
  • “list all project alerts”
  • “create an alert for high-value transactions”
  • “list all dashboard boards”
  • “list charts in a board”
  • “list all tracked contracts”
  • “register a new smart contract”
  • “list user segments”
  • “import wallet addresses”