> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formo.so/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> Query wallet profiles, run SQL analytics, manage dashboards, alerts, contracts, segments, and more - directly from your terminal or via AI agents.

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

<CardGroup cols={2}>
  <Card title="Profiles" icon="user" href="/cli/profiles">
    Fetch, search, and update wallet profiles and labels
  </Card>

  <Card title="Query" icon="database" href="/cli/query">
    Run SQL queries on your data
  </Card>

  <Card title="Analytics" icon="chart-mixed" href="/cli/analytics">
    Run pre-built analytics pipes (KPIs, funnels, retention, revenue)
  </Card>

  <Card title="Events" icon="send" href="/cli/events">
    Send raw analytics events with a project SDK write key
  </Card>

  <Card title="Boards" icon="table-columns" href="/cli/boards">
    Create and manage dashboard boards
  </Card>

  <Card title="Charts" icon="chart-line" href="/cli/charts">
    Create and manage charts within custom dashboards
  </Card>

  <Card title="Alerts" icon="bell" href="/cli/alerts">
    Configure project alerts
  </Card>

  <Card title="Contracts" icon="file-contract" href="/cli/contracts">
    Register and manage tracked smart contracts
  </Card>

  <Card title="Segments" icon="users" href="/cli/segments">
    Create and manage user segments
  </Card>

  <Card title="Import" icon="file-import" href="/cli/import">
    Import wallet addresses
  </Card>
</CardGroup>

## 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:

```bash theme={null}
npm install -g @formo/cli
```

Or run without installing using `npx`:

```bash theme={null}
npx @formo/cli
```

## Quick start

```bash theme={null}
# 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.

<Tabs>
  <Tab title="Login command">
    Save your API key to the local config file (`~/.config/formo/config.json`):

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Environment variable">
    Set the `FORMO_API_KEY` environment variable:

    ```bash theme={null}
    export FORMO_API_KEY=formo_abc123
    ```

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

<Info>
  Get your API key from **Settings → API** in the [Formo dashboard](https://app.formo.so).
</Info>

## Global commands

### `formo login`

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

```bash theme={null}
formo login formo_abc123
```

***

### `formo logout`

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

```bash theme={null}
formo logout
```

<Note>
  If the `FORMO_API_KEY` environment variable is set, `logout` will warn you to also run `unset FORMO_API_KEY`.
</Note>

***

### `formo status`

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

```bash theme={null}
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` |
| `--full-output` | 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.

```bash theme={null}
# 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:

```bash theme={null}
# Print a compact command manifest for discovery
formo --llms

# Print detailed command documentation, including options and examples
formo --llms-full

# Inspect one command's argument and option schema
formo profiles search --schema

# 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
```

`--llms` and `--llms-full` print documentation without executing API operations. Use `--llms` to find a command, then its `--help` or `--schema` output to construct a request. For scripts and agents, use `--format json` and supply `FORMO_API_KEY` through the environment. The key determines the active project and permitted scopes.

### Formo Analytics skill

Install the repository's analytics skill for Claude Code and Codex:

```bash theme={null}
npx skills add getformo/cli --skill formo-analytics --global \
  --agent claude-code --agent codex
```

The skill explains when to use the CLI, REST API, or [hosted Formo MCP](/mcp/overview). The hosted MCP additionally provides live schema and endpoint discovery, documentation search, natural-language SQL, and tools such as `project_users`, `distinct_values`, `cohort_analysis`, and `web_vitals`. These MCP-only endpoints are not CLI analytics subcommands or public REST pipe routes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.