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

# Getting Started

> Install the Tokenomist CLI, authenticate, and run your first command.

<Note>
  Requires **Node.js 18+** and a Tokenomist API key. Get one at [tokenomist.ai](https://tokenomist.ai).
</Note>

Tokenomist-cli brings the Tokenomist platform to your terminal. Query token unlocks, supply allocations, emission schedules, fundraising history, and buyback activity — response comes back in a structured, machine-readable format, so it drops straight into agents, notebooks, and research scripts.

## Installation

<Tabs>
  <Tab title="npm (recommended)">
    ```bash theme={null}
    npm install -g @tokenomist-ai/tokenomist-cli
    ```

    Verify the installation:

    ```bash theme={null}
    tok --version
    # 0.1.0
    ```
  </Tab>

  <Tab title="npx (no install)">
    Run any command without installing globally:

    ```bash theme={null}
    npx @tokenomist-ai/tokenomist-cli token list
    ```
  </Tab>
</Tabs>

Source code : [https://github.com/tokenomist-ai/tokenomist-cli](https://github.com/tokenomist-ai/tokenomist-cli)

## Authentication

<Steps>
  <Step title="Get your API key">
    1. Sign up or log in at [tokenomist.ai](https://tokenomist.ai)
    2. Navigate to the API section of your [dashboard](https://tokenomist.ai/profile#my-api-key) (Request API Trial [Here](https://docs.google.com/forms/d/e/1FAIpQLSebUG7Dq2mffAxoUfxbpSaN-GwUSB4vxmWA1PEobJlzcVesuw/viewform))
    3. Generate a new API key and copy it
  </Step>

  <Step title="Log in">
    <CodeGroup>
      ```bash Interactive (recommended) theme={null}
      tok auth login
      # Enter your Tokenomist API key: ****
      ```

      ```bash Non-interactive theme={null}
      tok auth login --api-key tk-your-api-key
      ```
    </CodeGroup>

    Your key is stored in `~/.tokenomist/config.json` with restricted file permissions (`0600`).
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    tok auth status
    # Source:  ~/.tokenomist/config.json
    # Key:    tk-t****ab2f
    ```
  </Step>
</Steps>

## Run Your First Command

```bash theme={null}
tok token list --token-id ethena,solana
```

You should see a formatted table with market data, supply, and unlock information:

```text theme={null}
+--------+--------+--------+----------------+------------------+------------------+------------------+----------------------+
| ID     | Name   | Symbol |     Market Cap |     Circ. Supply |           Locked |         Unlocked | Updated              |
+--------+--------+--------+----------------+------------------+------------------+------------------+----------------------+
| ethena | Ethena | ENA    |    976,183,624 |    8,759,375,000 |    4,928,125,000 |    8,048,437,500 | 2025-09-17T05:49:03Z |
| solana | Solana | SOL    | 49,279,843,463 | 575,499,265.8197 | 142,169,244.1616 | 644,999,130.1059 | 2025-08-07T08:37:39Z |
+--------+--------+--------+----------------+------------------+------------------+------------------+----------------------+
```

## AI Skills

Install 6 pre-built skills for Claude Code, Cursor, Windsurf, and other AI agents that can run shell commands.

```bash theme={null}
npx skills add tokenomist-ai/tokenomist-cli
```

| Skill                             | What it does                            |
| --------------------------------- | --------------------------------------- |
| `tokenomist-token-overview`       | Browse tokens, compare market caps      |
| `tokenomist-allocation-breakdown` | Supply distribution across stakeholders |
| `tokenomist-unlock-analysis`      | Analyze unlock schedules and impact     |
| `tokenomist-emission-report`      | Daily/weekly emission breakdowns        |
| `tokenomist-burn-buyback`         | Burn and buyback activity               |
| `tokenomist-fundraising-lookup`   | Funding rounds, investors, valuations   |

<Tip>
  Once installed, your AI agent can query tokenomics data directly — just ask it to "check Solana's upcoming unlocks" or "compare Arbitrum's emissions this month."
</Tip>

## Authentication Methods

The CLI resolves your API key in this order (first match wins):

| Priority | Method                       | Example                                           |
| -------- | ---------------------------- | ------------------------------------------------- |
| 1        | `--api-key` flag             | `tok token list --api-key tk-...`                 |
| 2        | `TOKENOMIST_API_KEY` env var | `export TOKENOMIST_API_KEY=tk-...`                |
| 3        | Config file                  | `~/.tokenomist/config.json` (set by `auth login`) |

<Tip>
  Use `auth login` for day-to-day work. Use env vars for CI/CD pipelines and Docker containers. Use the `--api-key` flag for one-off commands or testing with a different key.
</Tip>

### Environment variable

```bash theme={null}
export TOKENOMIST_API_KEY=tk-your-api-key
tok token list
```

### `.env` file

Create a `.env` file in your project directory:

```text theme={null}
TOKENOMIST_API_KEY=tk-your-api-key
```

## Output Formats

Every command supports three output formats via the `-o` / `--output` flag:

<Tabs>
  <Tab title="Table (default)">
    Human-readable formatted table with colored headers and right-aligned numbers.

    ```bash theme={null}
    tok token list
    ```
  </Tab>

  <Tab title="JSON">
    Structured output for scripts and AI agents.

    ```bash theme={null}
    tok token list --output json
    ```
  </Tab>

  <Tab title="CSV">
    Spreadsheet-ready output for Excel, Google Sheets, or data pipelines.

    ```bash theme={null}
    tok token list --output csv > tokens.csv
    ```
  </Tab>
</Tabs>

## Caching

The CLI caches API responses for **10 minutes** to reduce redundant requests and speed up repeated queries. Cache files are stored in `~/.tokenomist/cache/`.

To bypass the cache and fetch fresh data:

```bash theme={null}
tok token list --no-cache
```

## Uninstalling

```bash theme={null}
npm uninstall -g tokenomist-cli
```

<Warning>
  To also remove stored credentials and cache, run `rm -rf ~/.tokenomist`. This cannot be undone.
</Warning>