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

<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 my data
  </Card>

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

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

## 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 Keys** 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)     |

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

```bash theme={null}
# 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"
* "set the display name and twitter handle on a wallet profile"
* "tag a wallet as vip"
* "remove a label from a wallet profile"
* "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"