> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-platform-1/xyb-ledger/integrate-with-xyb-ledger/ledger-setup-and-configuration/install-and-setup-the-ledger-cli-tool.md).

# Install & Setup the Ledger CLI Tool

This guide walks you through setting up the **XYB Ledger CLI**, a lightweight command-line interface for configuring and managing your Ledger environment.

### Prerequisites

Ensure the following tools are installed:

| Tool | Version Required                                       |
| ---- | ------------------------------------------------------ |
| Java | 21+ (OpenJDK recommended)                              |
| OS   | macOS or Linux (Windows users can use WSL or Git Bash) |

**Note:** This guide assumes your Ledger service is already provisioned and running, either hosted remotely by XYB or on a private cloud. Contact your environment administrator if unsure.

### Step 1: Download the CLI JAR

You can download the latest stable CLI tool (JAR file) using either `curl` or `wget`.

```bash
curl -L -o luca-cli.jar "https://download.xyb.co/release/luca-cli/0.9.0/luca-cli-0.9.0.jar?Expires=2524608000[…]Z0GAmKep805lOTFtPIG3E10zo15yo8Mw__&Key-Pair-Id=K3VEG1D2XW7W1L"
```

***

### Step 2: Create a CLI Wrapper Script

Instead of typing `java -jar luca-cli.jar` each time, let’s simplify:

1. Create a script file:

   ```bash
   touch luca
   ```
2. Open it with a text editor:

   ```bash
   nano luca
   ```
3. Paste the following line into the file (update the path to your `.jar` file if needed):

   ```bash
   java -jar ./luca-cli.jar "$@"
   ```

> If the JAR is in the same directory as your script, you can use:

```bash
java -jar ./luca-cli.jar "$@"
```

4. Save and exit (`Ctrl + O`, `Enter`, then `Ctrl + X`).
5. Make it executable:

   ```bash
   chmod +x luca
   ```

Now you can use the CLI like this:

```bash
./luca list-agents
```

***

### Step 3: Connect the CLI to Ledger 

1. Add an instance in the following format:

<pre class="language-bash"><code class="lang-bash"><strong>./luca add-instance &#x3C;instance-name> &#x3C;url>
</strong></code></pre>

* `<instance-name>`: Any friendly name (e.g., `my-ledger`)
* `<url>`: The Ledger environment URL provided by XYB.

2. Add temporary internal authentication (for setup purposes, no signing key required):\
   &#x20;

   ```bash
   ./luca add-auth service/cac-ledger-svc
   ```

   (You are temporarily using a trusted internal agent to complete setup.)

3. Set the instance as default:<br>

   ```bash
   ./luca configure default-instance <instance-name>
   ```

4. Test the connection:

   ```bash
   ./luca list-agents
   ```

## Step 4: Set Up Your Own Application Agent (Optional)

If you **do not** already have a private key from authentication setup, you can generate one using the CLI:

```bash
./luca generate-key
```

Default algorithm: Ed25519.

Other examples:

```bash
./luca generate-key RSA 2048
./luca generate-key EC P-256
```

This creates a public/private key pair in your terminal directory.

* Register the public key with XYB, [see details](https://docs.xyb.co/overview/xyb-platform-overview/platform-authentication).
* Keep the **private** key secure, you will use it for authentication.

***

## Step 5: Create Cohort, Role, and Agent

1. Set your application cohort:&#x20;

**Note:** This must match how your agent was registered. Your cohort was already provisioned for you by XYB during onboarding. This step simply tells the CLI which cohort you will work inside.

```bash
./luca write-cohort application
```

2. Create an ADMIN role:

```bash
./luca write-role ADMIN "access+read+write+transition@/*/**"
```

3. Add Your Agent. Replace `<your-agent-name>` with your registered agent name (e.g., `application/ext-invoice`).

   ```bash
   ./luca write-agent application/<your-agent-name> --r:ADMIN
   ```

#### 5. Switch Authentication to Your Own Agent

1. Now update your CLI to authenticate using your real agent and private key:

```bash
./luca add-auth application/<your-agent-name> --signing-alg=EdDSA --jwt-key=<location-of-your-private-key>
```

2. Set CLI authentication identity:

```bash
./luca set-auth application/<your-agent-name>
```

## Step 6: Transition Ledger to Mastering Mode

Finally, switch Ledger into MASTERING mode:

```bash
./luca transition /service MASTERING
```

Now your Ledger environment is fully initialized!

You now have:

* The CLI tool downloaded
* A script for easier use
* An instance connected
* Permissions configured

From here, you can continue with setting up messaging channels, cohorts, or interacting with the API.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.xyb.co/xyb-platform-1/xyb-ledger/integrate-with-xyb-ledger/ledger-setup-and-configuration/install-and-setup-the-ledger-cli-tool.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.