@elsium-ai/cli

Command-line interface for scaffolding, developing, evaluating, and observing ElsiumAI projects.

Install

npm install -g @elsium-ai/cli

Or run commands directly without installing:

npx @elsium-ai/cli init my-ai-app

What’s Inside

Global options:

Commands

elsium init

Scaffolds a new ElsiumAI project with a complete directory structure, configuration files, example agents, tools, workflows, evaluations, and tests.

Usage

elsium init [name]

Arguments

The generated project includes:

Example

elsium init my-ai-app
cd my-ai-app
cp .env.example .env   # add your API keys
npm install
npm run dev

elsium dev

Starts a development server that watches your entry file for changes and automatically restarts on save. Powered by bun --watch under the hood.

Usage

elsium dev [entry]

Arguments

The command validates that the entry file exists and is inside the current working directory before starting the server. Press Ctrl+C to stop.

Example

# Start with default entry point
elsium dev

# Start with a custom entry file
elsium dev src/server.ts

elsium eval

Runs an evaluation suite defined in a TypeScript file against your agents or LLM pipelines. The eval file must export a default EvalSuiteConfig object (from @elsium-ai/testing) containing a name, an array of cases, and a runner function.

Usage

elsium eval <file>

Arguments

Running elsium eval without a file argument prints usage instructions and an example EvalSuiteConfig.

Each case in the suite can specify criteria such as:

• { type: 'contains', value: 'expected substring' }
• { type: 'length_min', value: 20 }

The command dynamically imports runEvalSuite and formatEvalReport from @elsium-ai/testing, runs all cases, prints a formatted report, and exits with code 1 if any case fails.

Example

# Run quality evaluations
elsium eval ./evals/quality.eval.ts

# Run determinism evaluations
elsium eval ./evals/determinism.eval.ts

elsium cost

Displays a formatted cost report from the last application run. The report is read from .elsium/cost-report.json, which is generated automatically when your app runs with cost tracking enabled.

Usage

elsium cost

This command takes no arguments or flags. If no cost report file exists, it prints instructions on how to enable cost tracking in your app configuration.

The report includes:

• Total cost (USD)
• Total tokens (input + output breakdown)
• Total API call count
• Per-model breakdown (cost, tokens, calls)

Example

elsium cost

Output:

  ElsiumAI Cost Report
  ──────────────────────────────────────────────────
  Generated: 2026-01-15T10:30:00.000Z

  Total Cost:          $0.003450
  Total Tokens:        1,250
    Input Tokens:      800
    Output Tokens:     450
  Total API Calls:     3

  By Model:
  ──────────────────────────────────────────────────
    claude-sonnet-4-6
      Cost:    $0.002100
      Tokens:  750
      Calls:   2
    claude-haiku-4-5
      Cost:    $0.001350
      Tokens:  500
      Calls:   1

To enable cost tracking, configure your app:

const app = createApp({
  observe: {
    costTracking: true,
  },
})

elsium trace

Lists recent traces or inspects a specific trace in detail. Traces are stored as JSON files in .elsium/traces/ and are recorded when tracing is enabled in your app configuration.

Usage

elsium trace           # List up to 20 recent traces
elsium trace <id>      # Inspect a specific trace by ID

Arguments

When listing traces, each entry shows its status (OK, ERR, or ...), trace ID, root span name, and duration.

When inspecting a single trace, the command renders a full span tree showing:

• Span kind, name, status, and duration
• Metadata key-value pairs
• Events with timestamps and optional data

Example

# List recent traces
elsium trace

# Inspect a specific trace
elsium trace trc_abc123

To enable tracing, configure your app:

const app = createApp({
  observe: {
    tracing: true,
  },
})

elsium xray

Inspects raw LLM call details including HTTP requests, responses, token usage, and cost. X-Ray data is captured when X-Ray mode is enabled on your gateway and stored in .elsium/xray-history.json.

Usage

elsium xray                   # Show the last call
elsium xray --last N          # Show the last N calls
elsium xray --trace <id>      # Show a specific call by trace ID
elsium xray --raw             # Include full request/response bodies

Flags

Each entry displays: trace ID, timestamp, provider, model, latency, token usage (input/output/total), and cost. When --raw is passed, the full HTTP request (method, URL, headers, body) and response (status, headers, body) are also printed.

Example

# Show the most recent LLM call
elsium xray

# Show the last 5 calls with full request/response bodies
elsium xray --last 5 --raw

# Look up a specific call
elsium xray --trace trc_abc123

To enable X-Ray mode, configure your gateway:

const gw = gateway({ provider: 'anthropic', apiKey: '...', xray: true })

elsium prompt

Manages versioned prompts stored as JSON files in .elsium/prompts/. Provides subcommands to list, inspect, compare, and view the history of prompt versions.

Usage

elsium prompt list                     # List all registered prompts
elsium prompt show <name> [version]    # Show prompt content (latest if version omitted)
elsium prompt history <name>           # Show version history for a prompt
elsium prompt diff <name> <v1> <v2>    # Show a line-by-line diff between two versions

Subcommands

Prompt files are JSON objects with the following shape:

{
  "name": "greeting",
  "version": "1.0",
  "content": "Hello {{user_name}}, how can I help you today?",
  "variables": ["user_name"],
  "metadata": {}
}

Example

# List all prompts
elsium prompt list

# Show the latest version of a prompt
elsium prompt show greeting

# Show a specific version
elsium prompt show greeting 1.0

# Compare two versions
elsium prompt diff greeting 1.0 2.0

# View version history
elsium prompt history greeting

elsium verify

Offline verification of a signed ExecutionProof (Verifiable Agent Execution). Recomputes the full event hash chain and validates the Ed25519 signature using a public key you supply. No API keys, no network calls — runs anywhere with just the proof file and the trusted public key.

Usage

elsium verify <proof.json> --public-key <pem-or-path>
elsium verify <proof.json> --trust-roots <path>

Options

Exit code is 0 if the proof verifies and 1 otherwise. Sample output:

✓ Signature valid (Ed25519, key=org-aperion-k7)
✓ Hash chain intact (47 events, head=a3f9b22c8e1f...)
  Events: 1 agent.input, 28 llm.call, 12 tool.call, 6 policy.evaluated
  Agent: invoice-extractor@1.2.3
  Span:  2026-05-24T18:00:00.000Z -> 2026-05-24T18:00:04.221Z

elsium replay

Compares two ExecutionProofs to assess reproducibility. Useful for post-mortem investigations and CI assertions (“the same agent run produces the same shape of execution”).

Usage

elsium replay <proof-a.json> <proof-b.json> [--strategy <bit-exact|structural>]

Options

Exit code is 0 when the proofs match under the chosen strategy and 1 otherwise.

elsium bom

Works with AI-BOMs — signed manifests of what an agent is made of (models, prompts, tools and their sandbox capabilities, MCP servers, eval datasets, policies, thresholds).

Usage

elsium bom verify <bom.json> --public-key <pem-or-path>
elsium bom verify <bom.json> --trust-roots <path>
elsium bom diff <approved.json> <current.json> [--fail-on <critical|major|minor>]

verify checks three layers offline: the components still hash to componentsHash, the header still hashes to digest, and digest carries a signature from a trusted key. Checks that never ran are reported as not checked rather than as failures.

diff is the release gate — it compares the shipped BOM against the approved one and exits non-zero when drift lands at or above --fail-on.

elsium bom diff ./approved-bom.json ./aibom.json --fail-on critical
# ✗ [critical] tool "wire_transfer" is present in the current BOM but was never approved
# ✗ 3 change(s): 1 critical, 1 major, 1 minor -- gate --fail-on=critical FAILED

Programmatic API

The package exports each command function for use in custom tooling, scripts, or programmatic integrations. All exports are available from the package entry point.

import {
  initCommand,
  devCommand,
  evalCommand,
  costCommand,
  traceCommand,
} from '@elsium-ai/cli'

initCommand

function initCommand(args: string[]): Promise<void>

Scaffolds a new ElsiumAI project. Pass the project name as the first element of args, or omit it to default to "my-elsium-app".

import { initCommand } from '@elsium-ai/cli'

await initCommand(['my-ai-app'])

devCommand

function devCommand(args: string[]): Promise<void>

Starts the development server with hot reload. Pass a custom entry file path as the first element of args, or omit it to default to "src/index.ts".

import { devCommand } from '@elsium-ai/cli'

await devCommand(['src/server.ts'])

evalCommand

function evalCommand(args: string[]): Promise<void>

Runs an evaluation suite. The first element of args must be the path to an eval file exporting a default EvalSuiteConfig. If no file is provided, prints usage information.

import { evalCommand } from '@elsium-ai/cli'

await evalCommand(['./evals/quality.eval.ts'])

costCommand

function costCommand(args: string[]): Promise<void>

Reads and displays the cost report from .elsium/cost-report.json. The args parameter is accepted for interface consistency but is currently unused.

import { costCommand } from '@elsium-ai/cli'

await costCommand([])

traceCommand

function traceCommand(args: string[]): Promise<void>

Lists recent traces when called with an empty args array, or inspects a specific trace when a trace ID is provided as the first element.

import { traceCommand } from '@elsium-ai/cli'

// List recent traces
await traceCommand([])

// Inspect a specific trace
await traceCommand(['trc_abc123'])

Part of ElsiumAI

This package is the CLI tooling layer of the ElsiumAI framework. See the Getting Started guide or the Fundamentals for comprehensive coverage of every feature.

Other packages in the framework:

• @elsium-ai/core — Runtime, policies, and utilities
• @elsium-ai/gateway — Multi-provider LLM gateway
• @elsium-ai/agents — Agent definitions and execution
• @elsium-ai/tools — Tool schemas and handlers
• @elsium-ai/workflows — Multi-step workflow orchestration
• @elsium-ai/observe — Tracing, cost tracking, and observability
• @elsium-ai/testing — Mocks, replay, and evaluation harness
• @elsium-ai/app — Application bootstrap and server

License

MIT