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

# Command Reference

> Complete reference for every Tokenomist CLI command, option, and flag.

## Global Options

These options are available on **all commands**:

| Flag                    | Description                                 | Default                     |
| ----------------------- | ------------------------------------------- | --------------------------- |
| `-k, --api-key <key>`   | API key (overrides env var and config file) | —                           |
| `-o, --output <format>` | Output format: `table`, `json`, `csv`       | `table`                     |
| `--base-url <url>`      | Override API base URL                       | `https://api.tokenomist.ai` |
| `--no-cache`            | Bypass the 10-minute response cache         | —                           |
| `-V, --version`         | Print CLI version                           | —                           |
| `-h, --help`            | Show help for any command                   | —                           |

<Tip>
  **Output formats:** `table` is best for terminal use, `json` for scripts and AI agents, `csv` for spreadsheets and data pipelines. Array values in CSV are joined with `"; "`.
</Tip>

***

## Authentication

### `tok auth login`

Store your API key securely in `~/.tokenomist/config.json`.

```bash theme={null}
# Interactive — prompts for key
tok auth login

# Non-interactive — pass key directly
tok auth login --api-key tk-your-api-key
```

| Option            | Description                                     |
| ----------------- | ----------------------------------------------- |
| `--api-key <key>` | API key (prompts interactively if not provided) |

The config file is created with restricted permissions (`0600`).

***

### `tok auth status`

Show the current authentication status including key source and masked key value.

```bash theme={null}
tok auth status
# Source:  ~/.tokenomist/config.json
# Key:    tk-t****ab2f
```

***

### `tok auth logout`

Remove the stored API key from `~/.tokenomist/config.json`.

```bash theme={null}
tok auth logout
```

***

## Tokens

### `tok token list`

List all tracked tokens with market data and supply information.

```bash theme={null}
tok token list
tok token list --token-id 1,2,3
tok token list --output json
```

| Option             | Description                           |
| ------------------ | ------------------------------------- |
| `--token-id <ids>` | Filter by token IDs (comma-separated) |

**Response fields:** `id`, `name`, `symbol`, `marketCap`, `circulatingSupply`, `maxSupply`, `totalLockedAmount`, `tbdLockedAmount`, `unlockedAmount`, `untrackedAmount`, `listedMethod`, `hasStandardAllocation`, `hasFundraising`, `latestFundraisingRound`, `hasBurn`, `hasBuyback`, `hasAnnouncedClaim`, `websiteUrl`, `lastUpdatedDate`

***

### `tok token search <query>`

Search for tokens by name, symbol, or slug.

```bash theme={null}
tok token search bitcoin
tok token search sol --output json
```

| Argument | Required | Description         |
| -------- | -------- | ------------------- |
| `query`  | Yes      | Search query string |

**Response fields:** `tokenId`, `tokenName`, `tokenSymbol`

***

## Unlocks

### `tok unlock list`

List unlock events grouped by token. Supports extensive filtering.

```bash theme={null}
tok unlock list
tok unlock list --min-market-cap 1000000
tok unlock list --standard-allocation founderTeam,privateInvestors
tok unlock list --min-value-to-market-cap 0.05 --page 1 --page-size 10
```

| Option                              | Description                            |
| ----------------------------------- | -------------------------------------- |
| `--min-market-cap <value>`          | Minimum market cap filter              |
| `--min-released-percentage <value>` | Minimum released percentage            |
| `--min-unlock-date <date>`          | Min unlock date (`YYYY-MM-DD`)         |
| `--max-unlock-date <date>`          | Max unlock date (`YYYY-MM-DD`)         |
| `--min-total-unlock-amount <value>` | Minimum total unlock amount            |
| `--min-value-to-market-cap <value>` | Min value-to-market-cap ratio          |
| `--standard-allocation <names>`     | Filter by allocation (comma-separated) |
| `--page <number>`                   | Page number                            |
| `--page-size <number>`              | Items per page                         |

<Note>
  **Allocation values:** `community`, `founderTeam`, `privateInvestors`, `publicInvestors`, `reserve`, `others`
</Note>

***

### `tok unlock upcoming`

List the next upcoming unlock event per token.

```bash theme={null}
tok unlock upcoming
tok unlock upcoming --min-market-cap 100000000 --output json
tok unlock upcoming --start 2024-08-01 --end 2024-08-31
```

| Option                              | Description                            |
| ----------------------------------- | -------------------------------------- |
| `--start <date>`                    | Start date (`YYYY-MM-DD`)              |
| `--end <date>`                      | End date (`YYYY-MM-DD`)                |
| `--standard-allocation <names>`     | Filter by allocation (comma-separated) |
| `--min-market-cap <value>`          | Minimum market cap                     |
| `--min-released-percentage <value>` | Minimum released percentage            |
| `--min-total-unlock-amount <value>` | Minimum total unlock amount            |
| `--min-value-to-market-cap <value>` | Min value-to-market-cap ratio          |
| `--page <number>`                   | Page number                            |
| `--page-size <number>`              | Items per page                         |

***

### `tok unlock events <tokenId>`

Get unlock events for a specific token with optional date range and allocation filters.

```bash theme={null}
tok unlock events solana
tok unlock events solana --start 2024-01-01 --end 2024-12-31
tok unlock events arbitrum --standard-allocation founderTeam --output json
```

| Argument  | Required | Description                                  |
| --------- | -------- | -------------------------------------------- |
| `tokenId` | Yes      | Token ID or slug (e.g. `solana`, `arbitrum`) |

| Option                          | Description                            |
| ------------------------------- | -------------------------------------- |
| `--start <date>`                | Start date (`YYYY-MM-DD`)              |
| `--end <date>`                  | End date (`YYYY-MM-DD`)                |
| `--standard-allocation <names>` | Filter by allocation (comma-separated) |
| `--page <number>`               | Page number                            |
| `--page-size <number>`          | Items per page                         |

**Response fields:** `unlockDate`, `tokenName`, `tokenSymbol`, `listedMethod`, `dataSource`, `cliffUnlocks` (containing `cliffAmount`, `cliffValue`, `valueToMarketCap`, `allocationBreakdown`), `latestUpdateDate`

***

## Emissions

### `tok emission daily <tokenId>`

Get daily emission data for a token, broken down by allocation.

```bash theme={null}
tok emission daily arbitrum
tok emission daily arbitrum --start 2024-08-01 --end 2024-08-31
tok emission daily solana --standard-allocation founderTeam --output csv
```

| Argument  | Required | Description |
| --------- | -------- | ----------- |
| `tokenId` | Yes      | Token ID    |

| Option                          | Description                            |
| ------------------------------- | -------------------------------------- |
| `--start <date>`                | Start date (`YYYY-MM-DD`)              |
| `--end <date>`                  | End date (`YYYY-MM-DD`)                |
| `--standard-allocation <names>` | Filter by allocation (comma-separated) |
| `--page <number>`               | Page number                            |
| `--page-size <number>`          | Items per page                         |

**Response fields:** `startDate`, `endDate`, `tokenName`, `tokenSymbol`, `listedMethod`, `unlockAmount`, `unlockValue`, `referencePrice`, `totalCumulativeUnlockedAmount`, `allocations` (containing `allocationName`, `standardAllocationName`, `unlockAmount`, `unlockValue`)

***

### `tok emission weekly <tokenId>`

Get weekly emission data for a token, broken down by allocation.

```bash theme={null}
tok emission weekly arbitrum
tok emission weekly arbitrum --start 2024-01-01 --end 2024-06-30
tok emission weekly solana --output json
```

| Argument  | Required | Description |
| --------- | -------- | ----------- |
| `tokenId` | Yes      | Token ID    |

| Option                          | Description                            |
| ------------------------------- | -------------------------------------- |
| `--start <date>`                | Start date (`YYYY-MM-DD`)              |
| `--end <date>`                  | End date (`YYYY-MM-DD`)                |
| `--standard-allocation <names>` | Filter by allocation (comma-separated) |
| `--page <number>`               | Page number                            |
| `--page-size <number>`          | Items per page                         |

**Response fields:** Same as `emission daily`.

***

## Allocations

### `tok allocation detail <tokenId>`

Get the standardized allocation distribution for a token — who owns what, and how much is locked vs unlocked.

```bash theme={null}
tok allocation detail solana
tok allocation detail solana --output json
```

| Argument  | Required | Description |
| --------- | -------- | ----------- |
| `tokenId` | Yes      | Token ID    |

**Response fields:** `allocationName`, `allocationType`, `standardAllocationName`, `allocationAmount`, `allocationUnlockedAmount`, `allocationLockedAmount`, `trackedAllocationPercentage`

**Standard allocation categories:**

| Category           | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `community`        | Community-allocated tokens (airdrops, rewards, ecosystem) |
| `founderTeam`      | Tokens allocated to founders and team members             |
| `privateInvestors` | Tokens allocated to private sale investors                |
| `publicInvestors`  | Tokens allocated to public sale participants              |
| `reserve`          | Treasury or reserve allocations                           |
| `others`           | Other or uncategorized allocations                        |

***

## Investors

### `tok investor list`

List all investors with optional date filters.

```bash theme={null}
tok investor list
tok investor list --start-latest-funding-date 2024-01-01
tok investor list --output json
```

| Option                               | Description                                         |
| ------------------------------------ | --------------------------------------------------- |
| `--start-latest-funding-date <date>` | Start date filter for latest funding (`YYYY-MM-DD`) |
| `--end-latest-funding-date <date>`   | End date filter for latest funding (`YYYY-MM-DD`)   |
| `--page <number>`                    | Page number                                         |
| `--page-size <number>`               | Items per page                                      |

***

### `tok investor detail <investorId>`

Get an investor's portfolio and funding round history.

```bash theme={null}
tok investor detail 123
tok investor detail 123 --is-lead-investor
tok investor detail 123 --funding-date-min 2024-01-01 --output json
```

| Argument     | Required | Description |
| ------------ | -------- | ----------- |
| `investorId` | Yes      | Investor ID |

| Option                         | Description                              |
| ------------------------------ | ---------------------------------------- |
| `--is-lead-investor`           | Filter to rounds where investor was lead |
| `--funding-date-min <date>`    | Minimum funding date                     |
| `--funding-date-max <date>`    | Maximum funding date                     |
| `--raised-amount-min <amount>` | Minimum raised amount                    |
| `--raised-amount-max <amount>` | Maximum raised amount                    |

***

## Fundraising

### `tok fundraising detail <tokenId>`

Get fundraising data for a specific token — rounds, investors, valuations.

```bash theme={null}
tok fundraising detail uniswap
tok fundraising detail solana --output json
tok fundraising detail arbitrum --funding-date-min 2023-01-01
```

| Argument  | Required | Description |
| --------- | -------- | ----------- |
| `tokenId` | Yes      | Token ID    |

| Option                         | Description           |
| ------------------------------ | --------------------- |
| `--funding-date-min <date>`    | Minimum funding date  |
| `--funding-date-max <date>`    | Maximum funding date  |
| `--raised-amount-min <amount>` | Minimum raised amount |
| `--raised-amount-max <amount>` | Maximum raised amount |

**Response fields:** `fundingRound`, `fundingDate`, `raiseType`, `amountRaised`, `valuation`, `pricePerToken`, `sourceURLList`, `numberOfInvestors`, `investors` (containing `investorId`, `investorName`, `isLeadInvestor`)

***

## Burns

### `tok burn list`

List all tokens that have burn event data.

```bash theme={null}
tok burn list
tok burn list --token-id 1,2,3
tok burn list --output json
```

| Option                 | Description                           |
| ---------------------- | ------------------------------------- |
| `--token-id <ids>`     | Filter by token IDs (comma-separated) |
| `--page <number>`      | Page number                           |
| `--page-size <number>` | Items per page                        |

***

### `tok burn detail <tokenId>`

Get burn events for a specific token.

```bash theme={null}
tok burn detail solana
tok burn detail ethereum --start 2024-01-01 --end 2024-12-31
tok burn detail bnb --output json
```

| Argument  | Required | Description |
| --------- | -------- | ----------- |
| `tokenId` | Yes      | Token ID    |

| Option           | Description               |
| ---------------- | ------------------------- |
| `--start <date>` | Start date (`YYYY-MM-DD`) |
| `--end <date>`   | End date (`YYYY-MM-DD`)   |

**Response fields:** `burnEventLabel`, `burnType`, `burnDate`, `amount`, `metadata` (containing `burners`, `burnReasons`)

***

## Buybacks

### `tok buyback list`

List all tokens that have buyback event data.

```bash theme={null}
tok buyback list
tok buyback list --token-id 1,2,3
tok buyback list --output json
```

| Option                 | Description                           |
| ---------------------- | ------------------------------------- |
| `--token-id <ids>`     | Filter by token IDs (comma-separated) |
| `--page <number>`      | Page number                           |
| `--page-size <number>` | Items per page                        |

***

### `tok buyback detail <tokenId>`

Get buyback events for a specific token.

```bash theme={null}
tok buyback detail solana
tok buyback detail bnb --start 2024-01-01 --end 2024-12-31
tok buyback detail bnb --output json
```

| Argument  | Required | Description |
| --------- | -------- | ----------- |
| `tokenId` | Yes      | Token ID    |

| Option           | Description               |
| ---------------- | ------------------------- |
| `--start <date>` | Start date (`YYYY-MM-DD`) |
| `--end <date>`   | End date (`YYYY-MM-DD`)   |

**Response fields:** `buybackEventLabel`, `buybackType`, `buybackDate`, `tokenAmount`, `value`, `spentAmount`, `spentUnit`, `targetAddress`, `buyerAddress`, `resolution`, `basis`

***

## Utilities

### `tok schema`

Print the full command schema as JSON — useful for tooling, documentation generation, and AI agent discovery.

```bash theme={null}
tok schema
tok schema --pretty
tok schema --pretty | jq '.commands | keys'
```

| Option     | Description                      |
| ---------- | -------------------------------- |
| `--pretty` | Pretty-print with 2-space indent |

***

## Environment Variables

| Variable               | Description                                                                    | Default                     |
| ---------------------- | ------------------------------------------------------------------------------ | --------------------------- |
| `TOKENOMIST_API_KEY`   | API key for authentication                                                     | —                           |
| `TOKENOMIST_BASE_URL`  | Custom API base URL                                                            | `https://api.tokenomist.ai` |
| `TOKENOMIST_NO_BANNER` | Set to `1` to suppress the welcome banner when running `tok` with no arguments | —                           |
| `NO_UPDATE_NOTIFIER`   | Set to `1` to disable update check notifications                               | —                           |
| `CI`                   | Set to `1` to disable update notifier and welcome banner in CI environments    | —                           |

***

## Error Handling

The CLI handles errors with descriptive messages and automatically retries transient failures with exponential backoff (up to 3 attempts with 1s, 2s, 4s delays plus jitter).

| Error          | Cause                        | Solution                                             |
| -------------- | ---------------------------- | ---------------------------------------------------- |
| `UNAUTHORIZED` | Missing or invalid API key   | Run `tok auth login` or check your key               |
| `RATE_LIMITED` | Too many requests            | Wait and retry, or reduce request frequency          |
| `NOT_FOUND`    | Invalid token ID or resource | Check the ID with `tok token search`                 |
| `SERVER_ERROR` | API server issue             | Retry after a moment — the CLI retries automatically |