# Voltage CLI

Use the **Voltage CLI** to work with the Voltage API from your terminal. The `voltage` command lets you inspect wallets, create and track payments, work with quotes and webhooks, and automate account operations. You can run commands yourself or ask your coding agent to run them for you.

The CLI is open source and available for macOS, Linux, and Windows. See the [Voltage CLI repository](https://github.com/voltagecloud/voltage-cli) for source code and the full reference.

## Let your coding agent help

If your agent has the current [Agent Skill Pack](/agent-skills), its `voltage-api` skill includes knowledge of the CLI: installation, authentication, profiles, commands, and payment outcomes. An agent with terminal access can help install the CLI and drive it on your behalf.

Install the skill pack with Node.js/npm available:

```bash
npx skills add voltagecloud/agent-skills --global --all
```

This installs skills across supported agent harnesses. Omit `--all` to choose agents interactively. Installing the skills does not install the CLI or sign in to Voltage. If you installed the pack before CLI support was added, update it using the instructions on the Agent Skill Pack page.

Open a new agent session and try:

> Use the voltage-api skill to install the Voltage CLI for my operating system and help me sign in and configure a profile.

Once connected, you can ask:

- “Use the Voltage CLI to check the network and available balance of my development wallet.”
- “List the completed payments in my configured environment.”
- “Verify that my wallet is on Mutinynet, then create a Lightning invoice for 150 sats and give me the invoice.”
- “Check whether that invoice has been paid.”

Complete browser login yourself when prompted. Give the agent the intended environment, wallet, and task; keep credentials out of the conversation. The CLI and its profiles use your existing account permissions.

## Install the CLI yourself

1. Open the official [releases page](https://github.com/voltagecloud/voltage-cli/releases/latest).
2. Download the archive matching your operating system and processor, plus `SHA256SUMS` from the same release.
3. Compare the archive's SHA-256 checksum with its entry in `SHA256SUMS`. Use `shasum -a 256 FILE` on macOS, `sha256sum FILE` on Linux, or `Get-FileHash FILE -Algorithm SHA256` in PowerShell, replacing `FILE` with the downloaded archive.
4. Extract the archive and put `voltage` (Windows: `voltage.exe`) in a directory on your `PATH`.

| Platform | Archive target |
| --- | --- |
| macOS, Apple Silicon | `aarch64-apple-darwin` |
| macOS, Intel | `x86_64-apple-darwin` |
| Linux, ARM64 | `aarch64-unknown-linux-gnu` |
| Linux, x86-64 | `x86_64-unknown-linux-gnu` |
| Windows, x86-64 | `x86_64-pc-windows-msvc` |

Verify the installation:

```bash
voltage --version
voltage --help
```

The examples on this page use release **v0.1.0**. Check the release instructions and your installed command's `--help` when using another version.

## Sign in and select an environment

Start with browser login:

```bash
voltage login --account work
voltage organizations list --account work
voltage environments list --account work --org ORG_ID
```

Follow the browser prompt to sign in and complete MFA. On a remote machine, add `--no-browser` and open the verification URL yourself.

Replace `ORG_ID` and `ENV_ID` below with the IDs for your intended organization and environment. Save them in a profile:

```bash
voltage profiles create dev --org ORG_ID --env ENV_ID --account work
voltage wallets list --profile dev
```

A profile saves your organization, environment, and credential selection. The name `dev` is just a label: inspect the selected wallet's network before making test payments. If you need a development wallet, start with the [Wallet Setup Guide](/wallet-setup-guide) and [Staging Environment](/staging-environment).

## Inspect wallets and payments

Use a wallet ID from the list above:

```bash
voltage wallets get WALLET_ID --profile dev
voltage payments list --profile dev --statuses completed
```

Add `--json` for scripts or agent use:

```bash
voltage wallets get WALLET_ID --profile dev --json
```

## Create a test Lightning invoice

With a confirmed Mutinynet Bitcoin wallet, create a 150-sat invoice:

```bash
voltage payments receive --profile dev --wallet WALLET_ID \
  --currency btc --kind bolt11 --amount 150 --unit sats --wait ready
```

`--wait ready` waits for the invoice to be available. Pay it from another compatible test wallet, then use the returned payment ID to check settlement:

```bash
voltage payments get PAYMENT_ID --profile dev --wait completed --timeout 120
```

An accepted request or a generated invoice does not mean the payment is complete. If the wait times out, keep the payment ID and check it again. See the [command reference](https://github.com/voltagecloud/voltage-cli/blob/v0.1.0/docs/commands.md) for additional operations.

## Use an API key for automation

For scripts, import an environment API key using the hidden input prompt:

```bash
voltage auth import-key --account ci --org ORG_ID --env ENV_ID
voltage profiles create automation --org ORG_ID --env ENV_ID --account ci
voltage wallets list --profile automation --json
```

Create the key in the intended environment as described in the [Developer Guide](/developer-guide). Organization and environment discovery commands require browser login; obtain those IDs before configuring key-based automation.

The CLI normally stores credentials in your operating system's credential store. For headless Linux without an unlocked Secret Service, use `--credential-store file` when importing the key; this stores credentials in an owner-only file. CLI profiles live under `$XDG_CONFIG_HOME/voltage` or `~/.config/voltage`. The CLI does not read the agent skill's direct-request helper file at `~/.voltage/.env`.

For automated payments, inspect the returned business outcome as well as the command's exit code. Reconcile an uncertain submission by its existing payment ID before retrying. Commands returning one-time secrets, such as webhook creation, support `--output-file PATH` to save the response privately.

## Find more commands

```bash
voltage payments --help
voltage payments receive --help
voltage webhooks --help
```

Use the [CLI README](https://github.com/voltagecloud/voltage-cli/blob/v0.1.0/README.md) for more examples and output conventions. For building an application integration, continue with the [Developer Guide](/developer-guide) and [Voltage API reference](https://voltageapi.com/v1/docs).