# Develop with AI

### Overview

`ledger-enterprise-cli` is a command-line interface for **AI agents and developers** to interact with Ledger Enterprise programmatically. It wraps the same request-based governance model as the platform: accounts, transactions, requests, approvals — all policy-enforced, all auditable.

Primary use case: an AI agent holds API operator credentials, initiates requests via the CLI, and completes approvals without a context switch to the web app. Administrators define rules in Ledger Enterprise; the CLI is how agents execute under those rules.

The CLI enforces the latest published version at runtime. If your installed version is outdated, it will block and prompt you to upgrade before processing any command.

### Setup

`Requires: Node.js ≥ 22`

#### Install

```
// bash
npm install -g ledger-enterprise-cli
```

#### Authenticate — API credentials *(recommended for agent workflows)*

Set the following environment variables before running login api. API key credentials are not accepted as CLI flags.

<table><thead><tr><th width="334.73046875">Environment variable</th><th width="107.828125">Required</th><th>Description</th></tr></thead><tbody><tr><td>LEDGER_ENTERPRISE_API_URL</td><td>Yes</td><td>Base URL of your Ledger Enterprise instance</td></tr><tr><td>LEDGER_ENTERPRISE_WORKSPACE</td><td>Yes</td><td>Workspace name</td></tr><tr><td>LEDGER_ENTERPRISE_API_KEY_ID</td><td>Yes</td><td>API key ID</td></tr><tr><td>LEDGER_ENTERPRISE_API_KEY_SECRET</td><td>Yes</td><td>API key secret</td></tr><tr><td>LEDGER_ENTERPRISE_API_PRIVATE_KEY</td><td>Optional</td><td>Hex-encoded PEM private key for the API operator. Required only when approving requests programmatically via requests sign. Not needed for read operations or device-based approval.</td></tr></tbody></table>

```
// bash
ledger-enterprise-cli login api \
  --baseUrl   $LEDGER_ENTERPRISE_API_URL \
  --workspace $LEDGER_ENTERPRISE_WORKSPACE
```

#### Authenticate — Ledger device (Stax or Flex)

```
// bash
ledger-enterprise-cli login device \
  --baseUrl   $LEDGER_ENTERPRISE_API_URL \
  --workspace $LEDGER_ENTERPRISE_WORKSPACE
```

{% hint style="info" %}
Requires a connected Ledger Stax or Flex. No API key secret is involved in this path.
{% endhint %}

#### End a session

```
// bash
ledger-enterprise-cli logout 
```

***

### Agent Skill

The CLI ships a bundled **agent skill** — a Markdown guide that instructs AI agents how to use the CLI correctly: authentication, command syntax, approval workflows, confirmation requirements, and error handling. The skill follows the shared SKILL format and works with any compatible AI assistant.

#### Install the skill

```
// bash
# Write skill files to the directory your assistant reads from
ledger-enterprise-cli skill install --path <YOUR_SKILLS_DIR>

# Or print to stdout and pipe/copy manually
ledger-enterprise-cli skill install
```

{% hint style="info" %}
**Refresh after upgrades.** The skill is versioned with the CLI binary. Re-run `skill install` after each `npm update -g ledger-enterprise-cli` to keep the agent’s instructions in sync with the available commands.
{% endhint %}

The skill covers:

* Session setup and credential handling
* Full command reference with required options and output shapes
* API-user approval workflow: getChallenge → sign → approve api
* Confirmation requirements for write and critical operations
* Exit codes and error handling

***

### Command Reference

All commands return JSON to stdout. Use the global `--pretty` flag for indented output. Authentication (`login`) is required before any resource command.

#### Global options

| Flag          | Description                        |
| ------------- | ---------------------------------- |
| -- pretty     | Indent JSON output                 |
| --debug       | Enable verbose diagnostic logs     |
| --timestamps  | Add timestamps to log lines        |
| -v, --version | Print installed CLI version        |
| -h, --help    | Help for any command or subcommand |

#### Accounts

| Command                                    | Description                          |
| ------------------------------------------ | ------------------------------------ |
| accounts list \[--page] \[--pageSize]      | Paginated list of workspace accounts |
| accounts get --id \<id>                    | Single account by ID                 |
| accounts getBalance --id \<id> \[--id ...] | Balances for one or more accounts    |

#### Transactions

| Command                                                             | Description                                            |
| ------------------------------------------------------------------- | ------------------------------------------------------ |
| transactions list --accountId \<id> \[--cursor]                     | Transaction history for an account (cursor pagination) |
| transactions estimate --accountId \<id> --transactionData '\<json>' | Fee estimate for a transaction payload                 |

#### Requests

| Command                                            | Description                                                                                 |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| requests list \[--page] \[--pageSize]              | Paginated list of workspace requests                                                        |
| requests get --id \<id>                            | Single request by ID                                                                        |
| requests create --requestData '\<json>'            | Create a new request                                                                        |
| requests getChallenge --id \<id>                   | Fetch approval challenge (API user session only)                                            |
| requests sign --challenge \<payload>               | Sign a challenge locally using LEDGER\_ENTERPRISE\_API\_PRIVATE\_KEY; returns signature JWT |
| requests approve api --id \<id> --signature \<jwt> | Submit API-user approval using signature from sign                                          |
| requests approve device --id \<id>                 | Complete approval on a connected Ledger device                                              |

{% hint style="info" %}
**API approval workflow**

`getChallenge` → `verify decoded payload` → `sign` → `approve api`.&#x20;

The private key never leaves the local machine — only the derived signature is sent to the server.
{% endhint %}

#### Users

| Command                            | Description                            |
| ---------------------------------- | -------------------------------------- |
| users list \[--page] \[--pageSize] | Paginated directory of workspace users |
| users get --id \<id>               | Single user by ID                      |

#### Groups

| Command                             | Description                             |
| ----------------------------------- | --------------------------------------- |
| groups list \[--page] \[--pageSize] | Paginated directory of workspace groups |
| groups get --id \<id>               | Single group by ID                      |

#### Policies

| Command                               | Description                          |
| ------------------------------------- | ------------------------------------ |
| policies list \[--page] \[--pageSize] | Paginated list of workspace policies |
| policies get --id \<id>               | Single policy by ID                  |

#### Whitelists

| Command                                 | Description                          |
| --------------------------------------- | ------------------------------------ |
| whitelists list \[--page] \[--pageSize] | Paginated list of address whitelists |
| whitelists get --id \<id>               | Single whitelist by ID               |

#### Exit codes

| Code | Meaning                                          |
| ---- | ------------------------------------------------ |
| 0    | Success                                          |
| 1    | General / network error                          |
| 2    | Validation error (missing option, invalid input) |
| 3    | Authentication error                             |
| 4    | Resource not found                               |
| 5    | Server error                                     |

### Important Legal Notice

*The Ledger Enterprise CLI is a technology feature that enables AI agents and developers to interact with Ledger Enterprise programmatically under administrator-defined governance rules. It is not a financial service, brokerage, investment adviser, or custodian. Ledger does not hold, manage, or have access to user assets at any time.*

*All requests initiated through this CLI are subject to the rules and approval policies defined by the user’s administrators in Ledger Enterprise. The user is solely responsible for the configuration of its governance policies, the credentials issued to API operators, and the logic, prompts, financial parameters, and outcomes of any transaction proposed or initiated by an AI agent. Ledger exercises no control over, and bears no responsibility for, the accuracy, profitability, suitability, or intent of any AI agent operating through this CLI. The user acknowledges that it uses this feature at its own risk.*

*Due to the non-deterministic nature of AI models, instructions generated by AI agents may contain errors, inaccuracies, or unintended parameters. Users must ensure appropriate human oversight of agent-initiated workflows.*

*The CLI includes a bundled agent skill that provides AI agents with instructions for authentication, command syntax, approval workflows, and error handling. This skill is provided as a developer resource only. It does not constitute a security audit, certification, or endorsement of any workflow or implementation built using it. Ledger does not guarantee that outputs generated by this skill are secure, correct, or free from vulnerabilities. The user is solely responsible for validating any agent behaviour informed by this skill against their own governance policies and security requirements.*

*This CLI and agent skill are provided "as is," in early development, without warranty of any kind. Features, APIs, and behaviours may change. Use of these features does not establish any contractual, advisory, or fiduciary relationship between the user or developer and Ledger SAS or its affiliates. To the maximum extent permitted by law, Ledger SAS and its affiliates shall not be liable for any direct, indirect, incidental, special, punitive, or consequential damages arising from use of these features, including but not limited to loss of digital assets, unauthorised access, smart contract exploits, or transaction malfunction.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.enterprise.ledger.com/api-documentation-v2/guides/develop-with-ai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.