CLI

Some links point to the service guide, which is in Korean.

The Bolta CLI is a command-line tool for issuing and managing tax invoices from the terminal. AI agents such as Claude Code can also use it to automate tax invoice tasks.

Installation

npm install -g @bolta-io/cli

Node.js 20.0.0 or later is required.

Authentication setup

Set your API key with an environment variable or a CLI command.

# Option 1: Environment variables (recommended)
export BOLTA_API_KEY="test_your_key"

# Option 2: CLI command (persistent storage - ~/.bolta/config.json)
bolta config set api-key test_your_key

# Test the connection
bolta config test

Authentication resolution priority: CLI flag (--api-key) > environment variable (BOLTA_API_KEY) > config file (~/.bolta/config.json)

For API key issuance, see the Developer Center API Key Management page.

Commands

Issuer management

The issuer command registers and retrieves issuers used for tax invoice issuance.

# Register an issuer
bolta issuer create --data '{
  "identificationNumber": "1234567890",
  "organizationName": "Test Corp.",
  "representativeName": "Gildong Hong"
}'

# Retrieve an issuer
bolta issuer get <issuerId>

Certificate management

# Retrieve the certificate registration URL
bolta certificate url <issuerId>

# Retrieve the certificate registration status
bolta certificate status <issuerId>

# Unregister the certificate
bolta certificate deregister <issuerId>

Tax invoice issuance / retrieval

Replace every YYYY-MM-DD placeholder in the examples below with the actual issuance or amendment date before running the command.

# Standard tax invoice issuance
bolta invoice issue --data '{
  "date": "YYYY-MM-DD",
  "purpose": "CLAIM",
  "taxType": "TAXABLE",
  "supplier": {
    "identificationNumber": "1234567890",
    "organizationName": "Supplier Corp.",
    "representativeName": "Gonggeup Kim",
    "manager": { "email": "supplier@example.com" }
  },
  "supplied": {
    "identificationNumber": "0987654321",
    "organizationName": "Recipient Corp.",
    "representativeName": "Gogaek Lee",
    "managers": [{ "email": "buyer@example.com" }]
  },
  "items": [{
    "date": "YYYY-MM-DD",
    "name": "Software development service",
    "supplyCost": 1000000,
    "tax": 100000
  }]
}'

# Retrieve a standard issuance sample for a recipient with a foreign registration number
# The CLI strips hyphens and spaces from the identification number before processing.
# Omit the top-level description or set it to null; passport numbers cannot be used.
bolta examples invoice-issue-foreign-supplied

# Request reverse issuance (recipient must use a business registration number only)
bolta invoice issue-request --data '{...}'

# Retrieve a tax invoice
bolta invoice get <issuanceKey>

# Retrieve status by Client-Reference-Id
bolta invoice status --reference-id <id>

Amendment

# Amendment: cancellation of contract
bolta invoice amend termination <issuanceKey> --date YYYY-MM-DD

# Amendment: change in supply cost
bolta invoice amend change-supply-cost <issuanceKey> --data '{
  "date": "YYYY-MM-DD",
  "taxType": "TAXABLE",
  "items": [{
    "date": "YYYY-MM-DD",
    "name": "Price adjustment",
    "supplyCost": -200000,
    "tax": -20000
  }]
}'

# Amendment: double issuance by mistake
bolta invoice amend double-issuance <issuanceKey>

The CLI first validates standard issuance, reverse issuance requests, and change-in-supply-cost amendment inputs using the same rules as the API. Check the latest schema with bolta schema invoice-issue.

Configuration

bolta config set <key> <value>   # api-key, base-url
bolta config show                # Show the current configuration
bolta config test                # Test the API connection

Input methods

Commands that require data support three input methods.

# Inline JSON (recommended for AI agents)
bolta invoice issue --data '{"date":"YYYY-MM-DD", ...}'

# File reference
bolta invoice issue --file invoice.json

# Pipe input
cat invoice.json | bolta invoice issue --stdin

Global options

Option	Description
`--api-key <key>`	Override the API key
`--verbose`	Print verbose logs (stderr)
`--dry-run`	Print only the request data without calling the API

Output format

The CLI prints every response as JSON to stdout.

// Success (exit code 0)
{ "success": true, "data": { ... } }

// Failure (exit code 1)
{ "success": false, "error": { "code": "...", "message": "...", "suggestion": "..." } }

Error codes

Code	Cause	Resolution
`AUTH_ERROR`	Missing or invalid API key	`bolta config set api-key <key>`
`VALIDATION_ERROR`	Invalid input data	Check the schema with `bolta schema <command>`
`INPUT_ERROR`	Invalid input method	Use one of `--data`, `--file`, or `--stdin`
`HTTP_400`	Bad request	Check error.message
`HTTP_403`	Issuer not found or inaccessible	Check issuerId and the API key
`HTTP_404`	Issuance request not found	Check issuanceKey
`HTTP_429`	Rate limit exceeded	Automatic retry (up to 3 times)
`NETWORK_ERROR`	Network error	Check your internet connection

AI guide

The CLI provides the following guides for AI agents.

Guide	Purpose	How to access
`CLAUDE.md`	Project guide that Claude Code reads automatically	Located in the project root
`llms.txt`	Reference document for general-purpose AI agents	Located in the project root
`bolta examples`	Ready-to-use sample JSON	`bolta examples [command]`
`bolta schema`	JSON input schema	`bolta schema [command]`
`--help`	Includes examples for every command	`bolta <command> --help`

# List available examples
bolta examples

# Retrieve a standard issuance sample JSON
bolta examples invoice-issue

# Retrieve a standard issuance sample JSON for a recipient with a foreign registration number
bolta examples invoice-issue-foreign-supplied

# Retrieve the standard issuance input schema
bolta schema invoice-issue

npm

npm package page

API Introduction

API Guides

Use Cases

SDK / No-code

Installation

Authentication setup

Commands

Issuer management

Certificate management

Tax invoice issuance / retrieval

Amendment

Configuration

Input methods

Global options

Output format

Error codes

AI guide

npm

​Installation

​Authentication setup

​Commands

​Issuer management

​Certificate management

​Tax invoice issuance / retrieval

​Amendment

​Configuration

​Input methods

​Global options

​Output format

​Error codes

​AI guide

npm

Installation

Authentication setup

Commands

Issuer management

Certificate management

Tax invoice issuance / retrieval

Amendment

Configuration

Input methods

Global options

Output format

Error codes

AI guide