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 for source code and the full reference.

Let your coding agent help

If your agent has the current Agent Skill Pack, 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:

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

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:

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:

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 and Staging Environment.

Inspect wallets and payments

Use a wallet ID from the list above:

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

Add --json for scripts or agent use:

voltage wallets get WALLET_ID --profile dev --json

Create a test Lightning invoice

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

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:

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 for additional operations.

Use an API key for automation

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

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

voltage payments --help
voltage payments receive --help
voltage webhooks --help

Use the CLI README for more examples and output conventions. For building an application integration, continue with the Developer Guide and Voltage API reference.