# CLI

`akkru` is the AkkruData command line, for your terminal, your scripts and AI agents that run shell commands. It needs Python 3.11 or later.

## Install

```bash
pipx install akkru
akkru setup
```

`uv tool install akkru` or `pip install akkru` also installs it. `akkru setup` downloads the tool definitions, installs the [AkkruData skill](/documents/agent-skills.md) for Claude Code and Codex when they are on the machine, and signs you in if you are not signed in yet.

## Sign in

| Command | What it does |
|---|---|
| `akkru auth login` | Opens the browser: sign in to AkkruData and click **Authorize**. With `--no-browser` it prints the address instead. |
| `akkru auth login --with-key` | Signs in with an [API key](https://www.akkrudata.ai/dashboard/api-keys): give the key after the option, type it when asked, or pipe it in. |
| `akkru auth status` | How this machine is signed in, and the credits left. |
| `akkru auth logout` | Signs out. |

When `AKKRU_API_KEY` is set, `akkru` uses that key instead of any saved sign-in. Use an API key for scripts, scheduled jobs, CI and servers. A browser sign-in is one of your account's [connections](/documents/mcp.md#managing-connections).

## Run a command

```text title="Usage"
akkru <tool> <action> [--flag value ...] [--json JSON]
```

Each command is one tool. The tool's page lists its actions, parameters and credits:

| Command | Tool |
|---|---|
| `akkru companies` | [Companies](/documents/companies.md) |
| `akkru filings` | [Filings](/documents/filings.md) |
| `akkru statements` | [Statements and notes](/documents/statements-and-notes.md) |
| `akkru facts` | [Financial facts](/documents/financial-facts.md) |
| `akkru metrics` | [Computed metrics](/documents/computed-metrics.md) |
| `akkru insider-transactions` | [Insider transactions (Form 4)](/documents/insider-transactions-form-4.md) |
| `akkru initial-holdings` | [Initial holdings (Form 3)](/documents/initial-holdings-form-3.md) |
| `akkru institutional-holdings` | [Institutional holdings (13F)](/documents/institutional-holdings-13f.md) |
| `akkru events` | [Corporate events (Form 8-K)](/documents/corporate-events-form-8-k.md) |
| `akkru account` | [Account](/documents/account.md) |

- A parameter that takes a single value is a flag, written with hyphens: `fiscal_year` is `--fiscal-year`.
- Lists and objects go in `--json`: a JSON object, `@FILE` to read one from a file, or `-` to read standard input.
- Every action takes `--detail full|light|minimal`, all charged the same.

```bash
akkru facts get --ticker AAPL --fiscal-year 2025 --json '{"line_items": ["revenue", "net income"]}'
```

## Help

| Command | Shows |
|---|---|
| `akkru --help` | The tools, the sign-in and setup commands, and the limits. |
| `akkru <tool> --help` | The tool's actions and their credits. |
| `akkru <tool> <action> --help` | The action's flags, its limit and an example. |
| `akkru schema <tool>.<action>` | Every parameter of the action, as JSON Schema. |
| `akkru help actions` | Every action of every tool. |
| `akkru help agent` | How an AI agent should use `akkru`. |
| `akkru --version` | The installed version. |

## Output

A command prints one JSON object on standard output: `{"ok": true, "data": ...}` with the reply in `data`, or `{"ok": false, "error": {...}}`. It is indented in a terminal and compact otherwise. The hint of a successful reply, and notices, go to standard error.

The error has the same fields as an [MCP error](/documents/mcp.md#errors), and `source` can also be `cli`: the error happened on this machine. `TOOL_FLAG_INVALID` means a flag's value is not of its parameter's type, or a list or an object was given as a flag.

| Exit code | Meaning |
|---|---|
| `0` | Success. |
| `1` | The API returned an error, or could not be reached. |
| `2` | The command was wrong, or failed on this machine. |
| `3` | A multi-page run stopped early. |
| `4` | Sign-in needed: not signed in, expired or disconnected. |

## Pages

`--pages N` fetches up to N pages (at most 2,000) of a paged action in one run, from `--page` (default 1), at the largest page size the action takes unless `--page-size` is given. Without `--yes` only the first page is fetched, and the reply says how to go on. Each page is charged. The pages come back as a list in `data`, with `next_page`. A run that stops early prints the pages it has, with a warning and `next_page`, and exits with code 3.

## Credits and limits

Each action costs the credits its tool page shows, from your account's balance, also when run from a script or a scheduled job. Calls refused with `source` `tool` or `cli` are not charged. `akkru account balance` shows the credits left.

Each account can make up to **120** tool calls a minute. The tool definitions can be downloaded up to **30** times a minute. Each tool action also has a limit: [MCP and CLI rate limits](/documents/credits-rate-limits.md#mcp-and-cli-rate-limits).

## Updating

When a newer version is out, `akkru` prints a notice. Upgrade with `pipx upgrade akkru`, `uv tool upgrade akkru` or `pip install -U akkru`, whichever installed it, then run `akkru setup` to update the skill.

## Files and environment variables

| Name | Purpose |
|---|---|
| `~/.akkru/` | The sign-in, the tool definitions and the other files `akkru` saves (`%USERPROFILE%\.akkru\` on Windows). |
| `AKKRU_API_KEY` | An API key, used instead of any saved sign-in. |
| `AKKRU_CONFIG_DIR` | Another folder for these files, instead of `~/.akkru/`. |
| `CLAUDE_CONFIG_DIR`, `CODEX_HOME` | Where `akkru setup` looks for Claude Code and Codex. |

## Uninstall

```bash
akkru uninstall --yes
pipx uninstall akkru
```

Without `--yes`, `akkru uninstall` only lists what it would remove. With `--yes` it signs out and removes the skill and the files `akkru` saved. Then remove the package with `pipx uninstall akkru`, `uv tool uninstall akkru` or `pip uninstall akkru`, whichever installed it.