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.

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:

   touch luca

2. Open it with a text editor:

   nano luca

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

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

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

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

1. Save and exit (Ctrl + O, Enter, then Ctrl + X).

2. Make it executable:

   chmod +x luca

Now you can use the CLI like this:

./luca list-agents

---

Step 3: Connect the CLI to Ledger

1. Add an instance in the following format:

./luca add-instance <instance-name> <url>

• <instance-name>: Any friendly name (e.g., my-ledger)

• <url>: The Ledger environment URL provided by XYB.

1. Add temporary internal authentication (for setup purposes, no signing key required):

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

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

2. Set the instance as default:

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

3. Test the connection:

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

./luca generate-key

Default algorithm: Ed25519.

Other examples:

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

• Keep the private key secure, you will use it for authentication.

---

Step 5: Create Cohort, Role, and Agent

1. Set your application cohort:

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.

./luca write-cohort application

1. Create an ADMIN role:

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

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

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

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

1. Set CLI authentication identity:

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

Step 6: Transition Ledger to Mastering Mode

Finally, switch Ledger into MASTERING mode:

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