Developers/CLI / API Reference

CLI / API Reference

Build on the same interface your terminal uses.

CLI syntax, automation, integrations, and diagnostics.

Command Contract

// The canonical task interface

The primary automation entry point is lucentracode run. Put the task in quotes, then use flags to control the workspace, model, agent, session, and output format.

bash

lucentracode run [options] "<task>"

# Example
lucentracode run --model auto --format json "run tests and summarize failures"

•<task>: the instruction LucentraCode should execute
•--model <model-id>: choose a specific model or use auto routing
•--agent <agent>: select build, plan, or review behavior
•--format json: emit machine-readable output for scripts and CI
•--dir <path>: run against another workspace directory
•--session <session-id> or --continue: resume existing work

Automation & CI/CD

// Repeatable, scriptable workflows

Use the non-interactive run command in pipelines, scheduled jobs, and repository checks. Keep the output format stable for the calling script and preserve the command output in CI logs.

Machine-readable result

lucentracode run --format json "run the test suite and summarize failures"

Run against another workspace

lucentracode run --dir ./services/api "add request validation"

Continue the previous session

lucentracode run --continue "implement the next step"

Specific session:lucentracode run --session <session-id> "continue this task"

Headless Runtime

// Connect another process to the CLI

Use the headless server when another workflow needs to interact with the LucentraCode runtime without opening the normal terminal interface.

Launch the server

lucentracode serve

Attach to a running server

lucentracode run --attach http://localhost:4096 "your task"

Check server health

lucentracode status --verbose

// NOTE:Keep a headless runtime behind your own network, authentication, and process controls.

MCP & External Tools

// Extend the runtime safely

List configured servers

lucentracode mcp list

Add a server

lucentracode mcp add

Authenticate a server

lucentracode mcp auth

Remove stored credentials

lucentracode mcp logout

// NOTE:MCP servers can read data, call tools, or change external systems. Only connect servers that you trust.

HTTP API

// For application integrations

The CLI is the primary interface. When an external service needs to trigger a verified workspace task, use the dispatch endpoint with a bearer token and a JSON request body.

bash

curl -X POST https://api.lucentracode.com/v1/dispatch \
  -H "Authorization: Bearer $LUCENTRACODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "github.com/my-org/core-service",
    "prompt": "Optimize SQL queries in billing module",
    "routingPolicy": "fast-verification"
  }'

•POST /v1/dispatch: trigger a repository task
•POST /v1/chat/completions: send an OpenAI-compatible model request

// NOTE:Treat the response schema, authentication requirements, and rate limits as versioned server contracts.

TypeScript SDK

// Embed execution in Node.js workflows

typescript

import { LucentraCodeClient } from '@lucentracode/sdk';

const client = new LucentraCodeClient({
  apiKey: process.env.LUCENTRACODE_API_KEY,
});

const execution = await client.agents.execute({
  workspace: './src',
  instruction: 'Migrate React class components to modern hooks',
  verify: { lint: true, tests: true },
});

console.log(execution.filesChanged);

Exit Status & Diagnostics

// Make failures actionable

Inspect command help

lucentracode --help
lucentracode run --help

Inspect runtime health

lucentracode status --verbose

Inspect usage

lucentracode usage --verbose

•0: the command completed successfully
•Non-zero: authentication, validation, runtime, model, tool, or task failure
•Interrupted commands: preserve the session ID if you need to resume the work