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

# Hyperline CLI

> An agent-first CLI to interact with your Hyperline account from the terminal

The [Hyperline CLI](https://www.npmjs.com/package/@hyperline/cli) lets you manage your billing operations directly from the terminal. It's designed to be **agent-first** — optimized for AI agents like Claude Code, Cursor, Windsurf, and any tool that can run shell commands.

## Why a CLI for AI agents?

AI agents work with tools to accomplish tasks. Today, most agents use MCP (Model Context Protocol) to connect to external services. While MCP works well, it has limitations when used at scale:

* **Context bloat** — MCP servers expose dozens of tools, each with full schemas that consume valuable context window space.
* **Slower on complex tasks** — For multi-step workflows, agents using MCP need to discover tools, read schemas, and format structured requests for each operation. On complex questions, MCP agents can loop for minutes trying to find the right tool combination.

CLIs solve these problems:

* **Token-efficient** — Short commands like `hyperline customers list` are natural for a text-predicting model to write and require minimal context to understand.
* **No tool discovery overhead** — Agents don't need to load a catalog of tools or read JSON schemas. They just run commands and read the output.
* **Composable** — CLI output can be piped, filtered with `jq`, or chained with other commands — patterns that agents handle natively.

## Installation

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

Verify the installation:

```bash theme={null}
hyperline --version
```

## Authentication

### Browser login

The simplest way to authenticate — opens your browser to securely log in with your Hyperline account:

```bash theme={null}
hyperline login
```

Credentials are stored locally in `~/.hyperline/`. To log out:

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

### API key

For server environments, CI/CD pipelines, or AI agents running without a browser:

```bash theme={null}
# Via environment variable
export HYPERLINE_API_KEY=sk_test_...

# Or inline
hyperline customers list --api-key sk_test_...
```

API keys can be generated from your account [Settings](https://app.hyperline.co/app/settings/api).

<Warning>
  Keep your API key secret. Do not commit it to version control — use environment variables or a secrets manager instead.
</Warning>

<Info>
  For sandbox environments, set the base URL via environment variable or flag:

  ```bash theme={null}
  export HYPERLINE_API_URL=https://api.sandbox.hyperline.co

  # Or per-command
  hyperline customers list --base-url https://api.sandbox.hyperline.co
  ```
</Info>

## Company selection

If you have access to multiple companies, the CLI uses the last used company by default. To switch to a specific company:

```bash theme={null}
hyperline company select
```

## Usage

The CLI follows a consistent `hyperline <resource> <action>` pattern:

```bash theme={null}
# List customers
hyperline customers list

# Get a specific invoice
hyperline invoices get --id inv_xxxxx

# Create a new customer
hyperline customers create --name "Acme Inc" --currency USD
```

### Available resources

| Resource             | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `customers`          | Create, update, list, and manage your customer base         |
| `subscriptions`      | Handle subscription lifecycle, cancellations, and templates |
| `invoices`           | Create, list, and manage invoices and transactions          |
| `products`           | Define and update your product catalog                      |
| `quotes`             | Generate and manage quotes                                  |
| `wallets`            | Prepaid wallet management and top-ups                       |
| `coupons`            | Create discount coupons and promotion codes                 |
| `webhooks`           | Configure webhook endpoints                                 |
| `payments`           | Track and manage payments                                   |
| `analytics`          | Access billing metrics                                      |
| `exports`            | Export your billing data                                    |
| `custom-properties`  | Extend resources with custom fields                         |
| `taxes`              | View tax rates and configurations                           |
| `invoicing-entities` | Manage your billing entities                                |

Use `--help` on any command to see available actions and options:

```bash theme={null}
hyperline customers --help
hyperline invoices list --help
```

### Output formats

By default, the CLI outputs human-readable text. Use `--output json` for structured output:

```bash theme={null}
# Human-readable output
hyperline customers list

# JSON output for scripting
hyperline customers list --output json

# Pipe to other tools
hyperline customers list --output json | jq '.[].name'
```

### Global options

| Option              | Description                                  |
| ------------------- | -------------------------------------------- |
| `--api-key <key>`   | API key (overrides `HYPERLINE_API_KEY`)      |
| `--base-url <url>`  | API base URL (overrides `HYPERLINE_API_URL`) |
| `--output <format>` | `json` or `text` (default: `text`)           |
| `--help`            | Show help                                    |
| `--version`         | Show version                                 |

## Setting up for AI agents

### Claude Code

Add the Hyperline CLI to your project's `CLAUDE.md` so Claude knows it's available:

```markdown theme={null}
## Tools

Hyperline CLI is available for billing operations.
Authenticate with: `export HYPERLINE_API_KEY=sk_...`
Usage: `hyperline <resource> <action> [options]`
Use `--output json` when you need to process the data.
```

### Cursor / Windsurf

Add instructions to your project rules (`.cursor/rules/` or `.windsurfrules`) so the agent knows to use the CLI:

```markdown theme={null}
## Billing

Use the Hyperline CLI for any billing-related tasks.
Run `hyperline <resource> <action>` commands in the terminal.
Use `--output json | jq` for filtering and processing data.
```

### Any agent with shell access

Any AI agent that can execute shell commands can use the Hyperline CLI. Set the `HYPERLINE_API_KEY` environment variable in the agent's environment, and the CLI is ready to use — no additional configuration or tool registration needed.

## CLI vs MCP — which should I use?

|                      | CLI                                                     | MCP                                                        |
| -------------------- | ------------------------------------------------------- | ---------------------------------------------------------- |
| **Best for**         | AI agents with shell access, scripting, automation      | AI assistants without terminal access (Claude.ai, ChatGPT) |
| **Setup**            | `npm install -g @hyperline/cli`                         | Add MCP server URL to your client                          |
| **Auth**             | API key or browser login                                | OAuth or API key                                           |
| **Context cost**     | Minimal — just command strings                          | Higher — full tool schemas loaded in context               |
| **Multi-step tasks** | Excellent — pipe, chain, and compose commands           | Can struggle with complex workflows                        |
| **Works with**       | Claude Code, Cursor, Windsurf, any terminal-based agent | Claude.ai, ChatGPT, any MCP-compatible client              |

You can use both. The MCP server is great for conversational AI assistants, while the CLI shines for agents that work in the terminal.

<Card title="Hyperline MCP Server" icon="robot" href="./mcp">
  Learn how to set up the Hyperline MCP server for AI assistants without terminal access.
</Card>