Skip to content

Lucid CLI Reference

The Lucid CLI (lucid) provides commands for deploying and managing AI agents, browsing the model catalog, and viewing passports.

Alpha Access Required

The Lucid CLI is available to alpha participants. Request access to get started.

Installation

pip install lucid-cli

Authentication

lucid login                    # Interactive login
LUCID_API_KEY=<key> lucid login  # API key via environment

Design Philosophy

The CLI is a lean provisioning bridge: it deploys infrastructure, checks status, and opens the Observer for visual management. Rich features (workspaces, workflows, access control, integrations) live in the Observer — the CLI gets you there with lucid open.

Core Commands

The CLI uses a simple mental model: edit YAML → apply → check status → view logs → open Observer

Command Description
lucid apply Deploy LucidEnvironment, LucidWorkspace, or LucidAgent resources from YAML
lucid diff Preview changes before applying
lucid status View agent status
lucid logs Stream agent logs
lucid start Start a stopped agent
lucid stop Stop a running agent
lucid teardown Clean up environment
lucid export Export cluster state to YAML

Observer Integration

Command Description
lucid open Open Observer dashboard in browser
lucid open <agent> Open agent detail page
lucid open <agent> --config Open agent configuration
lucid open <agent> --access Open agent access control
lucid open --workspace <id> Open workspace page
lucid open --workspace <id> --workflows Open workspace workflows
lucid open --workspace <id> --settings Open workspace settings
lucid open --workflows Open all workflows
lucid open --settings Open global settings
lucid open <target> --print Print URL instead of opening browser
lucid workspace list List all workspaces

Specialized Commands

Command Description
lucid login Authenticate with Lucid platform
lucid agent Manage agents (create, list, status, logs, start, stop, delete)
lucid verify Verify TEE attestation for endpoints or environments
lucid catalog Browse model and auditor catalog
lucid passport View AI passports
lucid auditor Develop, test, register, and manage ClaimsAuditor images
lucid policy Manage Cedar policies (validate, push, diff, list)
lucid model Register and manage self-hosted model endpoints
lucid optimization Manage compute optimization (status, setup, history, rollback)

lucid open

Open Observer UI pages in your browser. Uses webbrowser.open() — no extra dependencies.

lucid open [TARGET] [--workspace ID] [--config] [--access] [--workflows] [--settings] [--print]

Arguments: - TARGET - Agent name or ID (optional)

Options: - -w, --workspace ID - Open a workspace page (mutually exclusive with TARGET) - --config - Open agent configuration page - --access - Open agent access control page - --workflows - Open workflows page - --settings - Open settings page - -p, --print - Print URL instead of opening browser (useful in CI/headless)

Examples: 

lucid open                                  # Dashboard
lucid open my-agent                         # Agent page
lucid open my-agent --config                # Agent configuration
lucid open my-agent --access                # Agent access control
lucid open --workspace ws-123               # Workspace page
lucid open --workspace ws-123 --workflows   # Workspace workflows
lucid open --settings                       # Global settings
lucid open my-agent --print                 # Print URL only

lucid workspace

List and view workspaces (read-only). To create or manage workspaces, use the Observer UI.

Subcommand Description
lucid workspace list List all workspaces

lucid workspace list

List workspaces you have access to.

lucid workspace list [--json]

Options: - --json - Output as JSON

Examples: 

lucid workspace list
lucid workspace list --json

lucid verify

Verify TEE attestation for endpoints or environments.

Subcommand Description
lucid verify endpoint <url> Verify TEE attestation for an endpoint
lucid verify environment <env-id> Verify environment attestation
lucid verify operator [<url>] Verify operator attestation

lucid verify endpoint

Fetches the attestation report from the endpoint and verifies it against the hardware root of trust (Intel/AMD/AWS).

lucid verify endpoint <url> [--json] [--timeout SECONDS]

Options: - --json - Output as JSON - --timeout SECONDS - Request timeout in seconds (default: 10.0)

Examples: 

lucid verify endpoint https://env-abc123.serverless.lucid.ai
lucid verify endpoint https://my-model.example.com --json

lucid verify environment

Fetches routing information for the environment and verifies attestation for all available endpoints.

lucid verify environment <env-id> [--json]

Options: - --json - Output as JSON

Examples: 

lucid verify environment env-abc123def456

lucid verify operator

Verify the Lucid Operator is running in a genuine TEE.

lucid verify operator [<url>] [--version VERSION] [--digest DIGEST] [--json]

Arguments: - <url> - Operator URL to verify (default: https://operator.lucid.ai)

Options: - --version VERSION - Expected operator version - --digest DIGEST - Expected operator image digest - --json - Output as JSON

Examples: 

lucid verify operator
lucid verify operator --digest sha256:abc123...
lucid verify operator https://my-operator.example.com

lucid passport

View AI passports.

Subcommand Description
lucid passport list List passports
lucid passport show <passport-id> Show passport details

lucid passport list

List AI passports.

lucid passport list [--limit N] [--offset N] [--json]

Options: - --limit N - Max results (default: 20) - --offset N - Offset for pagination (default: 0) - --json - Output as JSON

lucid passport show

Show passport details.

lucid passport show <passport-id> [--json]

Options: - --json - Output as JSON

lucid catalog

Browse the serverless resource catalog (models, auditor profiles).

Subcommand Description
lucid catalog models List models available in the serverless catalog
lucid catalog auditors List auditor profiles

lucid catalog models

List models available in the serverless catalog.

lucid catalog models [--tee] [--region REGION] [--json]

Options: - --tee - Show only TEE-compatible models - -r, --region REGION - Filter by region - --json - Output as JSON

lucid catalog auditors

List auditor profiles available in the serverless catalog.

lucid catalog auditors [--json]

Options: - --json - Output as JSON

lucid auditor

Develop, test, register, and manage ClaimsAuditor images.

Subcommand Description
lucid auditor init <name> Scaffold a new ClaimsAuditor project
lucid auditor dev Local dev server with mock Gateway and hot-reload
lucid auditor test Run contract compliance tests (--claims validates /claims and /vocabulary)
lucid auditor register Register auditor with the platform (--claims declares claim vocabulary)
lucid auditor list List all auditors with trust tier and status
lucid auditor settings get/set View/configure effective settings with cascade indicators
lucid auditor schema <id> Inspect config schema fields
lucid auditor verify <image> Verify an auditor image's contract and labels
lucid auditor publish <image> Verify, sign, and push an auditor image

lucid auditor init

Scaffold a new ClaimsAuditor project with boilerplate files.

lucid auditor init <name> [--template TEMPLATE]

Arguments: - <name> - Name for the new auditor project (e.g., 'my-custom-auditor')

Options: - --template TEMPLATE - Project template to use (default: claims)

Examples: 

lucid auditor init my-pii-auditor
lucid auditor init financial-check --template advanced

The generated project includes: - main.py - ClaimsAuditor with @claims decorator and serve() entry point - config.py - Configuration dataclass with auditor-specific settings - Dockerfile - Container image definition with io.lucid.interfaces=health,claims,vocabulary labels - test_contract.py - Contract compliance tests (health, claims, vocabulary endpoints)

lucid auditor dev

Start a local development server with mock Gateway and hot-reload. Simulates the Gateway environment locally without requiring a Kubernetes cluster.

lucid auditor dev [--port PORT] [--reload]

Options: - --port PORT - Port to listen on (default: 8080) - --reload - Enable auto-reload on file changes (default: enabled)

Examples: 

lucid auditor dev
lucid auditor dev --port 9000

lucid auditor test

Run contract compliance tests against a ClaimsAuditor. Validates /health, /claims, and /vocabulary endpoints.

lucid auditor test [--image IMAGE] [--endpoint URL] [--claims]

Options: - --image IMAGE - Docker image to test (starts a container) - --endpoint URL - URL of a running auditor to test - --claims - Validate the ClaimsAuditor contract (default: true). Checks that /claims returns a claims array, /vocabulary declares all claim names, and all claim names in responses are declared in vocabulary.

Examples: 

lucid auditor test --image my-auditor:latest
lucid auditor test --endpoint http://localhost:8080
lucid auditor test --claims --endpoint http://localhost:8080

lucid auditor register

Register a ClaimsAuditor with the Lucid platform. After registration, the auditor appears in the catalog, agent creation wizard, and settings panels. The --claims flag syncs the auditor's vocabulary with the platform for Cedar policy autocomplete.

lucid auditor register [--mode MODE] [--endpoint URL] [--image IMAGE] [--claims] [--json]

Options: - --mode MODE - Deployment mode: sidecar, in-cluster, or external (default: external) - --endpoint URL - Auditor endpoint URL (required for external/in-cluster modes) - --image IMAGE - Container image with digest (required for sidecar mode) - --claims - Sync claim vocabulary from the auditor's /vocabulary endpoint (default: true) - --json - Output as JSON

Examples: 

lucid auditor register --mode external --endpoint https://my-auditor.example.com
lucid auditor register --mode sidecar --image ghcr.io/myorg/my-auditor@sha256:abc123
lucid auditor register --claims --endpoint https://my-auditor.example.com

lucid auditor list

List all auditors (built-in and custom registered) with trust tier and status.

lucid auditor list [--json]

Options: - --json - Output as JSON

lucid auditor settings

View or configure effective auditor settings with cascade indicators showing inheritance source.

lucid auditor settings get <auditor-id> [--scope SCOPE] [--scope-id ID] [--json]
lucid auditor settings set <auditor-id> <key> <value> [--scope SCOPE] [--scope-id ID] [--enforce]

Arguments: - <auditor-id> - Auditor identifier (e.g., 'lucid-llm-judge-auditor') - <key> - Setting key (for set) - <value> - Setting value (for set)

Options: - --scope SCOPE - Scope level: org, workspace, or agent (default: agent) - --scope-id ID - ID of the org, workspace, or agent - --enforce - Mark the setting as enforced (cannot be overridden at lower scopes) - --json - Output as JSON

Examples: 

lucid auditor settings get lucid-llm-judge-auditor --scope org
lucid auditor settings set lucid-llm-judge-auditor enablePii true --scope workspace --scope-id ws-123
lucid auditor settings set lucid-llm-judge-auditor injection_threshold 0.8 --scope org --enforce

lucid auditor schema

Inspect the config schema fields for an auditor. Shows field names, types, groups, descriptions, and defaults.

lucid auditor schema <auditor-id> [--json]

Arguments: - <auditor-id> - Auditor identifier

Options: - --json - Output as JSON

Examples: 

lucid auditor schema lucid-llm-judge-auditor
lucid auditor schema lucid-llm-judge-auditor --json

lucid auditor verify

Verify an auditor image's contract and labels. Performs a compliance probe on a local container image to ensure it meets the Lucid Auditor Standard.

lucid auditor verify <image> [--endpoint URL]

Arguments: - <image> - The tag of the local Docker image to verify (e.g., 'compliance-auditor:v1')

Options: - --endpoint URL - Verify a running external auditor endpoint instead of a local image

Examples: 

lucid auditor verify my-auditor:latest
lucid auditor verify --endpoint https://my-auditor.example.com

lucid auditor publish

Verify, sign, and push an auditor image. This is the primary way to release an Auditor to the Lucid network.

lucid auditor publish <image> [--registry REGISTRY] [--register]

Arguments: - <image> - The local image tag to publish

Options: - --registry REGISTRY - The target container registry (e.g., 'ghcr.io/my-org'). If not provided, skips the push step and only notarizes. - --register - Auto-register the auditor with the platform after publishing

The API key is read from the LUCID_API_KEY environment variable, or prompted interactively if not set.

lucid policy

Manage Cedar policies for agents, workspaces, and organizations.

Subcommand Description
lucid policy validate <file> Validate a Cedar policy file against the Lucid schema
lucid policy push <file> Push a Cedar policy to the platform
lucid policy pull Pull the effective Cedar policy for a scope
lucid policy diff Show differences between local and remote policy
lucid policy list List all policies with scope and version
lucid policy test <file> Test a Cedar policy against sample claims

lucid policy validate

Validate a Cedar policy file against the Lucid Cedar schema. Checks syntax, entity types, and claim references against known auditor vocabularies.

lucid policy validate <file> [--schema SCHEMA]

Arguments: - <file> - Path to a .cedar policy file

Options: - --schema SCHEMA - Path to a custom Cedar schema file (default: uses Lucid standard schema)

Examples: 

lucid policy validate policy.cedar
lucid policy validate my-org-policy.cedar --schema custom-schema.cedarschema

lucid policy push

Push a Cedar policy to the platform. Applies to the specified scope.

lucid policy push <file> [--scope SCOPE] [--scope-id ID] [--dry-run] [--json]

Arguments: - <file> - Path to a .cedar policy file

Options: - --scope SCOPE - Scope level: org, workspace, or agent (default: agent) - --scope-id ID - ID of the org, workspace, or agent - --dry-run - Validate and show what would change without applying - --json - Output as JSON

Examples: 

lucid policy push policy.cedar --scope agent --scope-id agent-abc123
lucid policy push org-baseline.cedar --scope org
lucid policy push policy.cedar --scope workspace --scope-id ws-123 --dry-run

lucid policy pull

Pull the effective Cedar policy for a scope. Shows the merged policy including inherited rules from parent scopes.

lucid policy pull [--scope SCOPE] [--scope-id ID] [--output FILE]

Options: - --scope SCOPE - Scope level: org, workspace, or agent (default: agent) - --scope-id ID - ID of the org, workspace, or agent - --output FILE - Write to file instead of stdout

Examples: 

lucid policy pull --scope agent --scope-id agent-abc123
lucid policy pull --scope org --output org-policy.cedar

lucid policy diff

Show differences between a local Cedar policy and the currently deployed policy.

lucid policy diff <file> [--scope SCOPE] [--scope-id ID]

Arguments: - <file> - Path to a local .cedar policy file

Options: - --scope SCOPE - Scope level: org, workspace, or agent - --scope-id ID - ID of the org, workspace, or agent

Examples: 

lucid policy diff policy.cedar --scope agent --scope-id agent-abc123

lucid policy list

List all Cedar policies with their scope, version, and status.

lucid policy list [--scope SCOPE] [--json]

Options: - --scope SCOPE - Filter by scope level - --json - Output as JSON

Examples: 

lucid policy list
lucid policy list --scope org
lucid policy list --json

lucid policy test

Test a Cedar policy against sample claims data. Useful for validating policy behavior before pushing.

lucid policy test <file> [--claims-file FILE] [--expect DECISION]

Arguments: - <file> - Path to a .cedar policy file

Options: - --claims-file FILE - JSON file with sample claims context - --expect DECISION - Expected decision: allow or deny

Examples: 

lucid policy test policy.cedar --claims-file test-claims.json --expect deny
lucid policy test policy.cedar --claims-file clean-claims.json --expect allow

lucid model

Register and manage self-hosted model endpoints.

Subcommand Description
lucid model register Register a self-hosted model with the platform
lucid model list List all models (Lucid-managed + self-hosted)
lucid model verify <id> Verify remote attestation for a registered model
lucid model test <id> Health check + inference smoke test

lucid model register

Register a self-hosted model endpoint with the Lucid platform. After registration, the model appears in the model catalog and agent creation wizard alongside Lucid-managed models.

lucid model register [--endpoint URL] [--mode MODE] [--model-type TYPE] [--image-digest DIGEST] [--json]

Options: - --endpoint URL - Model inference endpoint (must be OpenAI-compatible) - --mode MODE - Deployment mode: sidecar, in-cluster, or external (default: external) - --model-type TYPE - Model type: chat, completion, or embedding (default: chat) - --image-digest DIGEST - Container image digest for TEE verification (required for sidecar mode) - --json - Output as JSON

Examples: 

lucid model register --endpoint https://my-model.example.com --mode external
lucid model register --endpoint https://my-model.internal --mode in-cluster --model-type embedding

lucid model list

List all models (Lucid-managed and self-hosted) with trust tier and status.

lucid model list [--json]

Options: - --json - Output as JSON

lucid model verify

Verify remote attestation quote for a registered model. Checks the TEE hardware quote against the expected image digest.

lucid model verify <model-id> [--json]

Arguments: - <model-id> - Registered model identifier

Options: - --json - Output as JSON

Examples: 

lucid model verify my-custom-llm

lucid model test

Run a health check and inference smoke test against a registered model endpoint.

lucid model test <model-id> [--json]

Arguments: - <model-id> - Registered model identifier

Options: - --json - Output as JSON

Examples: 

lucid model test my-custom-llm

lucid agent

Manage agents (create, list, delete, status, logs, start, stop).

Subcommand Description
lucid agent create Create a new agent
lucid agent list List all agents
lucid agent status <agent-id> Get agent status
lucid agent logs <agent-id> Stream agent logs
lucid agent start <agent-id> Start a stopped agent
lucid agent stop <agent-id> Stop a running agent
lucid agent delete <agent-id> Delete an agent

lucid agent create

Create a new agent from flags or a YAML spec file.

lucid agent create [--name NAME] [--model MODEL] [--gpu GPU] [-f FILE] [--json]

Options: - -n, --name NAME - Agent name - -m, --model MODEL - Model to use - -g, --gpu GPU - GPU type - -f, --file FILE - YAML file with LucidAgent spec - --json - Output as JSON

Examples: 

lucid agent create --name my-agent --model llama3 --gpu H100
lucid agent create -f agent.yaml

# Create from a LucidAgent YAML definition
lucid agent create -f agent.yaml

The -f flag accepts a LucidAgent YAML resource (apiVersion: lucid.io/v1alpha1, kind: LucidAgent) with the full agent spec including identity, abilities, environment, actions, and auditor settings.

lucid agent list

List all agents with optional filtering and pagination.

lucid agent list [--limit N] [--offset N] [--type TYPE] [--json]

Options: - -l, --limit N - Max results (default: 20) - -o, --offset N - Offset for pagination (default: 0) - -t, --type TYPE - Filter by management type - --json - Output as JSON

Examples: 

lucid agent list
lucid agent list --type managed
lucid agent list --json

lucid agent status

Get the status of a specific agent.

lucid agent status <agent-id> [--k8s] [--json]

Arguments: - <agent-id> - Agent ID or name

Options: - --k8s - Show Kubernetes status details - --json - Output as JSON

Examples: 

lucid agent status agent-1
lucid agent status agent-1 --k8s
lucid agent status agent-1 --json

lucid agent logs

Stream or fetch logs from an agent.

lucid agent logs <agent-id> [-c CONTAINER] [--no-follow] [--tail N]

Arguments: - <agent-id> - Agent ID or name

Options: - -c, --container CONTAINER - Specific container name - --no-follow - Don't stream, just fetch recent logs - --tail N - Number of lines to show (default: 100)

Examples: 

lucid agent logs agent-1
lucid agent logs agent-1 -c sidecar
lucid agent logs agent-1 --no-follow

lucid agent start

Start a stopped agent.

lucid agent start <agent-id>

Arguments: - <agent-id> - Agent ID or name

lucid agent stop

Stop a running agent.

lucid agent stop <agent-id>

Arguments: - <agent-id> - Agent ID or name

lucid agent delete

Delete an agent. Prompts for confirmation unless -y is provided.

lucid agent delete <agent-id> [-y]

Arguments: - <agent-id> - Agent ID or name

Options: - -y, --yes - Skip confirmation

Examples: 

lucid agent delete agent-1
lucid agent delete agent-1 -y

lucid optimization

Manage compute optimization capabilities. The optimization system helps maximize GPU efficiency through static kernel analysis, live GPU monitoring, hardware counter verification, and automated optimization actions.

The system works in two dimensions:

Analysis Tiers determine what analysis features are available: - core - Static analysis only (always available) - enhanced - Adds live GPU info via NVML (requires device access) - advanced - Full hardware verification via DCGM

Action Tiers determine what automated actions can be taken: - none - Reporting only, no automated actions - restart - Can trigger pod restarts for recovery - runtime - Can modify runtime parameters (batch size, etc.) - full - Full automation including config updates and scaling

Subcommand Description
lucid optimization status Show current optimization capabilities
lucid optimization setup Interactive setup wizard
lucid optimization history Show recent optimization changes
lucid optimization rollback Rollback an optimization change

lucid optimization status

Show current optimization capabilities. Queries the compute auditor to determine what analysis and action tiers are available.

lucid optimization status [-n NAMESPACE] [--json]

Options: - -n, --namespace NAMESPACE - Kubernetes namespace (default: default) - --json - Output as JSON

Examples: 

lucid optimization status
lucid optimization status -n production
lucid optimization status --json

lucid optimization setup

Interactive setup wizard for optimization features. Generates and applies the Kubernetes resources needed for the requested optimization tiers.

lucid optimization setup [--action-tier TIER] [--analysis-tier TIER] [-n NAMESPACE] [--dry-run] [--interactive/--no-interactive]

Options: - -a, --action-tier TIER - Action tier: none, restart, runtime, or full (default: none) - -t, --analysis-tier TIER - Analysis tier: core, enhanced, or advanced (default: core) - -n, --namespace NAMESPACE - Kubernetes namespace (default: default) - --dry-run - Show what would be applied without applying - --interactive/--no-interactive - Enable or disable interactive mode (default: interactive)

Examples: 

lucid optimization setup
lucid optimization setup --action-tier runtime --analysis-tier enhanced
lucid optimization setup --dry-run
lucid optimization setup --no-interactive -a restart -t core

lucid optimization history

Show recent optimization changes. Queries the operator for the history of applied optimization changes, including rollbacks and their outcomes.

lucid optimization history [-n NAMESPACE] [-l LIMIT] [--json]

Options: - -n, --namespace NAMESPACE - Kubernetes namespace (default: default) - -l, --limit N - Maximum number of entries (default: 20) - --json - Output as JSON

Examples: 

lucid optimization history
lucid optimization history -n production -l 50
lucid optimization history --json

lucid optimization rollback

Manually rollback an optimization change. Reverts a specific optimization change or the most recent one. Must specify either --change-id or --latest.

lucid optimization rollback [--change-id ID] [--latest] [-n NAMESPACE] [-y] [--json]

Options: - -c, --change-id ID - Specific change ID to rollback - --latest - Rollback the most recent change - -n, --namespace NAMESPACE - Kubernetes namespace (default: default) - -y, --yes - Skip confirmation - --json - Output as JSON

Examples: 

lucid optimization rollback --latest
lucid optimization rollback --change-id abc123
lucid optimization rollback --latest -y

Command Reference

lucid

Deploy from YAML or create a serverless environment.

SERVERLESS MODE: lucid apply --app open-webui --model llama-3.1-8b SELF-HOSTED MODE: lucid apply -f environment.yaml -f workspace.yaml WORKSPACE ONLY: lucid apply -f workspace.yaml AGENT ONLY: lucid apply -f agent.yaml

Supports LucidEnvironment, LucidWorkspace, and LucidAgent resources. Multiple -f flags and multi-document YAML (--- separated) are supported.

The operator URL is auto-detected from: 1. LUCID_OPERATOR_URL environment variable 2. In-cluster service (if running in K8s) 3. localhost:8443 (default for local development)

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • -f, --file PATH: YAML files (LucidEnvironment, LucidWorkspace, LucidAgent). Repeatable.
  • --app TEXT: App ID for serverless mode
  • --model TEXT: Model ID for serverless mode
  • -p, --profile TEXT: Auditor profile [default: default]
  • -r, --region TEXT: Data residency (us, eu, apac, any) [default: any]
  • -n, --name TEXT: Environment name
  • --managed: Use Lucid managed deployment
  • -y, --yes: Skip confirmation
  • --skip-infra: Skip infrastructure provisioning
  • --json: Output as JSON
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Preview changes that would be applied.

Shows what infrastructure and agents would be created, updated, or deleted when running 'lucid apply'.

Examples: lucid diff -f env.yaml # Preview changes lucid diff -f env.yaml --validate-only # Validate only lucid diff -f env.yaml --json # JSON output

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • -f, --file PATH: LucidEnvironment YAML file [required]
  • --validate-only: Only validate, don't show diff
  • --json: Output as JSON
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Show status of all agents or a specific agent.

Without arguments, shows overview of all agents and local cluster status. With an agent name, shows detailed status for that agent.

Examples: lucid status # List all agents lucid status my-agent # Show specific agent lucid status --json # JSON output lucid status my-agent --k8s # Show K8s details

Usage:

console $ lucid [OPTIONS][AGENT_NAME] COMMAND [ARGS]...

Arguments:

  • [AGENT_NAME]: Agent name (optional)

Options:

  • --k8s: Show Kubernetes status details
  • --json: Output as JSON
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Start a stopped agent.

Examples: lucid start my-agent

Usage:

console $ lucid [OPTIONS] AGENT_NAME COMMAND [ARGS]...

Arguments:

  • AGENT_NAME: Agent name [required]

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Stream logs from an agent.

Examples: lucid logs my-agent # View recent logs lucid logs my-agent -f # Stream logs lucid logs my-agent --tail 50 # Last 50 lines lucid logs my-agent -c sidecar # Specific container

Usage:

console $ lucid [OPTIONS] AGENT_NAME COMMAND [ARGS]...

Arguments:

  • AGENT_NAME: Agent name [required]

Options:

  • -f, --follow: Stream logs continuously
  • --tail INTEGER: Number of tail lines [default: 100]
  • -c, --container TEXT: Specific container name
  • --json: Output as JSON
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Stream logs from an agent.

Examples: lucid logs my-agent # View recent logs lucid logs my-agent -f # Stream logs lucid logs my-agent --tail 50 # Last 50 lines lucid logs my-agent -c sidecar # Specific container

Usage:

console $ lucid [OPTIONS] AGENT_NAME COMMAND [ARGS]...

Arguments:

  • AGENT_NAME: Agent name [required]

Options:

  • -f, --follow: Stream logs continuously
  • --tail INTEGER: Number of tail lines [default: 100]
  • -c, --container TEXT: Specific container name
  • --json: Output as JSON
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Tear down the local Kind cluster and optionally remove Docker images.

Auto-detects the local Kind cluster (lucid-local-k8s). Use --images to also remove all lucid Docker images.

Examples: lucid teardown # Delete Kind cluster lucid teardown --images # Also remove Docker images lucid teardown -y # Skip confirmation

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • -y, --yes: Skip confirmation
  • --images: Also remove Docker images
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Export current cluster state as LucidEnvironment YAML.

Creates a LucidEnvironment YAML file from the current state of deployed agents. Useful for backup or migrating configurations.

Examples: lucid export my-env # Print to stdout lucid export my-env -o env.yaml # Save to file

Usage:

console $ lucid [OPTIONS] NAME COMMAND [ARGS]...

Arguments:

  • NAME: Environment name to export [required]

Options:

  • -o, --output TEXT: Output file (default: stdout)
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Authenticate with the Lucid platform.

Supports two modes: 1. Email/password login (JWT, optionally generates API key) 2. Direct API key via LUCID_API_KEY environment variable

Credentials are accepted via environment variables or interactive prompt to avoid exposure in process listings and shell history.

Environment variables: LUCID_API_KEY - API key for direct authentication LUCID_PASSWORD - Password (falls back to interactive prompt)

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • -e, --email TEXT: Account email address
  • --api-url TEXT: Override API base URL
  • --generate-key: Generate a persistent API key after login
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

lucid

Verify TEE attestation for endpoints or environments.

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • endpoint: Verify TEE attestation for an endpoint.
  • environment: Verify TEE attestation for a serverless...
  • operator: Verify the Lucid Operator is running in a...

lucid endpoint

Verify TEE attestation for an endpoint.

Fetches the attestation report from the endpoint and verifies it against the hardware root of trust (Intel/AMD/AWS).

Examples: lucid verify endpoint https://env-abc123.serverless.lucid.ai lucid verify endpoint https://my-model.example.com --json

Usage:

console $ lucid endpoint [OPTIONS] ENDPOINT

Arguments:

  • ENDPOINT: TEE endpoint URL to verify [required]

Options:

  • --json: Output as JSON
  • --timeout FLOAT: Request timeout in seconds [default: 10.0]
  • --help: Show this message and exit.

lucid environment

Verify TEE attestation for a serverless environment.

Fetches routing information for the environment and verifies attestation for all available endpoints.

Examples: lucid verify environment env-abc123def456

Usage:

console $ lucid environment [OPTIONS] ENVIRONMENT_ID

Arguments:

  • ENVIRONMENT_ID: Serverless environment ID [required]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid operator

Verify the Lucid Operator is running in a genuine TEE.

This command fetches the Operator's attestation report and verifies it against hardware root of trust. If verification passes, you can trust that the Operator is running legitimate, unmodified code.

The Operator is a key component in the serverless architecture that injects auditor sidecars into workload pods. Verifying the Operator ensures the injection logic has not been tampered with.

Examples: # Verify against Lucid's production Operator lucid verify operator

# Verify with specific expected measurements
lucid verify operator --digest sha256:abc123...

# Verify a custom Operator deployment
lucid verify operator https://my-operator.example.com

Usage:

console $ lucid operator [OPTIONS][OPERATOR_URL]

Arguments:

  • [OPERATOR_URL]: Operator URL to verify [default: https://operator.lucid.ai]

Options:

  • --version TEXT: Expected operator version
  • --digest TEXT: Expected operator image digest
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid

Browse the serverless resource catalog (apps, models, auditor profiles).

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • apps: List apps in the catalog.
  • show: Show details for a catalog app.
  • models: List models available in the serverless...
  • auditors: List auditor profiles available in the...

lucid apps

List apps in the catalog.

Usage:

console $ lucid apps [OPTIONS]

Options:

  • -c, --category TEXT: Filter by category
  • --verified: Show only verified apps
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid show

Show details for a catalog app.

Usage:

console $ lucid show [OPTIONS] APP_ID

Arguments:

  • APP_ID: App ID [required]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid models

List models available in the serverless catalog.

Usage:

console $ lucid models [OPTIONS]

Options:

  • --tee: Show only TEE-compatible models
  • -r, --region TEXT: Filter by region
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid auditors

List auditor profiles available in the serverless catalog.

Usage:

console $ lucid auditors [OPTIONS]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid

View AI passports.

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • list: List AI passports.
  • show: Show passport details.

lucid list

List AI passports.

Usage:

console $ lucid list [OPTIONS]

Options:

  • --limit INTEGER: Max results [default: 20]
  • --offset INTEGER: Offset for pagination [default: 0]
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid show

Show passport details.

Usage:

console $ lucid show [OPTIONS] PASSPORT_ID

Arguments:

  • PASSPORT_ID: Passport ID [required]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid

Manage Lucid Auditors

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • init: Scaffold a new auditor project from...
  • dev: Start the local development server with...
  • test: Run contract compliance tests against an...
  • register: Register an auditor with the Lucid platform.
  • list: List all registered auditors for your...
  • schema: Show the detection-tuning schema for an...
  • verify: Verify an auditor image's contract and...
  • publish: Verify, sign, and push an auditor image.
  • settings: Manage auditor settings

lucid init

Scaffold a new auditor project from templates.

Creates a project directory with all the files needed to develop a custom Lucid auditor, including a FastAPI server, config, Dockerfile, and contract compliance tests.

The project name is used as the directory name and substituted into template placeholders.

Examples: lucid auditor init my-toxicity-auditor lucid auditor init pii-scanner --output ~/projects

Usage:

console $ lucid init [OPTIONS] NAME

Arguments:

  • NAME: Name for the new auditor project [required]

Options:

  • -o, --output PATH: Parent directory (defaults to current directory)
  • --help: Show this message and exit.

lucid dev

Start the local development server with hot reload.

By default, uses Docker Compose to spin up the auditor and a mock chain service. Use --no-docker to run directly with uvicorn if you prefer a lighter-weight setup.

The dev server watches for file changes and automatically reloads.

Examples: lucid auditor dev lucid auditor dev --dir ./my-auditor lucid auditor dev --no-docker --port 9000

Usage:

console $ lucid dev [OPTIONS]

Options:

  • -d, --dir PATH: Auditor project directory (defaults to current directory)
  • -p, --port INTEGER: Port to bind the dev server to [default: 8090]
  • --no-docker: Run directly with uvicorn instead of Docker Compose
  • --help: Show this message and exit.

lucid test

Run contract compliance tests against an auditor.

Tests can either be run against a live URL (default: localhost:8090) or by executing the project's pytest suite.

When targeting a URL, the following contract checks are performed: 1. Health endpoint returns 200 with required fields 2. Claims endpoint accepts valid payload and returns list[Claim]

Examples: lucid auditor test lucid auditor test --url http://my-auditor:8090 lucid auditor test --dir ./my-auditor lucid auditor test --json

Usage:

console $ lucid test [OPTIONS]

Options:

  • -u, --url TEXT: Base URL of the running auditor [default: http://localhost:8090]
  • -d, --dir PATH: Run pytest on project's tests/ directory instead
  • --json: Output results as JSON
  • --help: Show this message and exit.

lucid register

Register an auditor with the Lucid platform.

Registers a custom auditor endpoint with the Auditor Registry so it can participate in the VAP audit chain. The Verifier will perform an initial health check during registration.

Use --mode shadow to test your auditor alongside production auditors without affecting decisions. Use --mode active when ready for production.

Use --claims to register the claim vocabulary produced by this auditor. This enables Cedar policies to reference specific claim names.

Examples: lucid auditor register --id my-auditor --name "My Auditor" --endpoint https://auditor.internal:8090 lucid auditor register --id pii-scanner --name "PII Scanner" --endpoint http://pii:8090 --mode active lucid auditor register --id tee-auditor --name "TEE Auditor" --endpoint https://tee:8090 --deployment-mode sidecar --image-digest sha256:abc lucid auditor register --id toxicity --name "Toxicity" --endpoint http://tox:8090 --claims toxicity.score,toxicity.label

Usage:

console $ lucid register [OPTIONS]

Options:

  • --id TEXT: Unique auditor identifier [required]
  • -n, --name TEXT: Display name [required]
  • -e, --endpoint TEXT: Auditor endpoint URL [required]
  • -d, --deployment-mode TEXT: Deployment mode: sidecar, in_cluster, or external [default: external]
  • --auth-type TEXT: Auth type: mtls, bearer, or api_key [default: api_key]
  • -m, --mode TEXT: Registration mode: shadow or active [default: shadow]
  • --description TEXT: Auditor description
  • --phases TEXT: Comma-separated supported phases (request,response,data_retrieval)
  • --image-digest TEXT: Container image digest for TEE attestation
  • --claims TEXT: Comma-separated claim vocabulary (e.g., 'toxicity.score,toxicity.label')
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid list

List all registered auditors for your organization.

Displays auditor ID, name, deployment mode, trust tier, status, and current health.

Examples: lucid auditor list lucid auditor list --json

Usage:

console $ lucid list [OPTIONS]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid schema

Show the detection-tuning schema for an auditor.

Displays the available detection-tuning fields, their types, defaults, and groupings. This information is used by the Observer UI to auto-generate settings panels. Enforcement is managed via Cedar policies, not per-field settings.

Examples: lucid auditor schema lucid-llm-judge-auditor lucid auditor schema lucid-llm-judge-auditor --json

Usage:

console $ lucid schema [OPTIONS] AUDITOR_ID

Arguments:

  • AUDITOR_ID: Auditor ID to show schema for [required]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid verify

Verify an auditor image's contract and labels.

This command performs a 'compliance probe' on a local container image to ensure it meets the Lucid Auditor Standard. It checks: 1. OCI Labels: Required metadata like fields, version, and phase. 2. API Contract: Starts an ephemeral instance and probes /health and /claims.

Args: image: The tag of the local Docker image to verify (e.g., 'compliance-auditor:v1').

Usage:

console $ lucid verify [OPTIONS] IMAGE

Arguments:

  • IMAGE: [required]

Options:

  • --help: Show this message and exit.

lucid publish

Verify, sign, and push an auditor image.

This is the primary way to release an Auditor to the Lucid network. It performs the following steps: 1. Verify: Runs the lucid auditor verify suite. 2. Sign: Calculates the image digest and signs it using the API key (HMAC). 3. Push: Uploads the image to the specified container registry. 4. Notarize: Registers the signed digest with the centralized Verifier service.

Args: image: The local image tag to publish. registry: The target container registry (e.g., 'ghcr.io/my-org'). If not provided, skips the push step and only notarizes.

The API key is read from the LUCID_API_KEY environment variable, or prompted interactively if not set.

Usage:

console $ lucid publish [OPTIONS] IMAGE

Arguments:

  • IMAGE: [required]

Options:

  • --registry TEXT
  • --help: Show this message and exit.

lucid settings

Manage auditor settings

Usage:

console $ lucid settings [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • get: Get auditor settings at a specific scope.
  • set: Set auditor settings at a specific scope.

lucid settings get

Get auditor settings at a specific scope.

Retrieves the raw settings for an auditor at the given scope level (org, workspace, or agent). Use this to inspect settings before making changes.

For the resolved effective configuration (with cascade), use the Observer UI or the API directly.

Examples: lucid auditor settings get lucid-llm-judge-auditor --scope org --scope-id lucid auditor settings get lucid-llm-judge-auditor --scope workspace --scope-id --json

Usage:

console $ lucid settings get [OPTIONS] AUDITOR_ID

Arguments:

  • AUDITOR_ID: Auditor ID [required]

Options:

  • -s, --scope TEXT: Scope: org, workspace, or agent [required]
  • --scope-id TEXT: UUID of the scope entity [required]
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid settings set

Set auditor settings at a specific scope.

Creates or updates the auditor settings at the given scope level. Settings can be provided as a JSON string or from a JSON file.

Settings at lower scopes (agent) override higher scopes (workspace, org). Enforcement is handled by Cedar policies, not by individual settings.

Examples: lucid auditor settings set lucid-llm-judge-auditor --scope org --scope-id --settings '{"jailbreak_detection": true}' lucid auditor settings set lucid-llm-judge-auditor --scope workspace --scope-id -f settings.json

Usage:

console $ lucid settings set [OPTIONS] AUDITOR_ID

Arguments:

  • AUDITOR_ID: Auditor ID [required]

Options:

  • -s, --scope TEXT: Scope: org, workspace, or agent [required]
  • --scope-id TEXT: UUID of the scope entity [required]
  • --settings TEXT: Settings as JSON string
  • -f, --file PATH: Path to JSON file with settings
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid

Manage agents

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • create: Create a new agent.
  • list: List all agents.
  • status: Get agent status.
  • logs: Stream agent logs.
  • start: Start a stopped agent.
  • stop: Stop a running agent.
  • delete: Delete an agent.
  • init: Scaffold a new VAP agent project from...
  • deploy: Prepare a VAP deployment for an agent...

lucid create

Create a new agent.

Examples: lucid agent create --name my-agent --model llama3 --gpu H100 lucid agent create -f agent.yaml

Usage:

console $ lucid create [OPTIONS]

Options:

  • -n, --name TEXT: Agent name
  • -m, --model TEXT: Model to use
  • -g, --gpu TEXT: GPU type
  • -f, --file PATH: YAML file with agent spec
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid list

List all agents.

Examples: lucid agent list lucid agent list --type managed lucid agent list --json

Usage:

console $ lucid list [OPTIONS]

Options:

  • -l, --limit INTEGER: Max results [default: 20]
  • -o, --offset INTEGER: Offset for pagination [default: 0]
  • -t, --type TEXT: Filter by management type
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid status

Get agent status.

Examples: lucid agent status agent-1 lucid agent status agent-1 --k8s lucid agent status agent-1 --json

Usage:

console $ lucid status [OPTIONS] AGENT_ID

Arguments:

  • AGENT_ID: Agent ID or name [required]

Options:

  • --k8s: Show Kubernetes status
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid logs

Stream agent logs.

Examples: lucid agent logs agent-1 lucid agent logs agent-1 -c sidecar lucid agent logs agent-1 --no-follow

Usage:

console $ lucid logs [OPTIONS] AGENT_ID

Arguments:

  • AGENT_ID: Agent ID or name [required]

Options:

  • -c, --container TEXT: Specific container
  • --no-follow: Don't stream, just fetch recent logs
  • --tail INTEGER: Number of lines to show [default: 100]
  • --help: Show this message and exit.

lucid start

Start a stopped agent.

Examples: lucid agent start agent-1

Usage:

console $ lucid start [OPTIONS] AGENT_ID

Arguments:

  • AGENT_ID: Agent ID or name [required]

Options:

  • --help: Show this message and exit.

lucid stop

Stop a running agent.

Examples: lucid agent stop agent-1

Usage:

console $ lucid stop [OPTIONS] AGENT_ID

Arguments:

  • AGENT_ID: Agent ID or name [required]

Options:

  • --help: Show this message and exit.

lucid delete

Delete an agent.

Examples: lucid agent delete agent-1 lucid agent delete agent-1 -y

Usage:

console $ lucid delete [OPTIONS] AGENT_ID

Arguments:

  • AGENT_ID: Agent ID or name [required]

Options:

  • -y, --yes: Skip confirmation
  • --help: Show this message and exit.

lucid init

Scaffold a new VAP agent project from templates.

Creates a project directory with all the files needed to build and deploy a Verifiable Agent Pod, including agent code, a Dockerfile extending lucid-agent-base, and an env var reference.

By default the Dockerfile uses lucid-agent-base (hardened, production). Pass --dev to use lucid-agent-dev (shell access, writable rootfs).

Examples: lucid agent init my-agent lucid agent init my-agent --dev lucid agent init my-agent --output ~/projects

Usage:

console $ lucid init [OPTIONS] NAME

Arguments:

  • NAME: Name for the new agent project [required]

Options:

  • -o, --output PATH: Parent directory (defaults to current directory)
  • --dev: Use the development base image (shell access, writable rootfs)
  • --help: Show this message and exit.

lucid deploy

Prepare a VAP deployment for an agent identity.

Generates a single-use bootstrap token and returns environment variables, a docker run command, and a Dockerfile snippet for deploying a Verifiable Agent Pod in your own infrastructure.

The bootstrap token expires after 1 hour.

Examples: lucid agent deploy 550e8400-e29b-41d4-a716-446655440000 lucid agent deploy 550e8400-... --image my-registry/agent-base:v2 lucid agent deploy 550e8400-... --json

Usage:

console $ lucid deploy [OPTIONS] IDENTITY_ID

Arguments:

  • IDENTITY_ID: Agent identity ID [required]

Options:

  • -i, --image TEXT: Base image reference [default: lucid-agent-base:latest]
  • --verifier-url TEXT: Override Verifier URL
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid

Manage compute optimization capabilities.

The optimization system helps maximize GPU efficiency through: - Static kernel analysis and recommendations - Live GPU monitoring (with NVML access) - Hardware counter verification (with DCGM) - Automated optimization actions

Use 'lucid optimization status' to see current capabilities. Use 'lucid optimization setup' to configure optimization features.

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • status: Show current optimization capabilities.
  • setup: Interactive setup wizard for optimization...
  • history: Show recent optimization changes.
  • rollback: Manually rollback an optimization change.

lucid status

Show current optimization capabilities.

Queries the compute auditor to determine what analysis and action tiers are available based on the current deployment configuration.

Examples: lucid optimization status lucid optimization status -n production lucid optimization status --json

Usage:

console $ lucid status [OPTIONS]

Options:

  • -n, --namespace TEXT: Kubernetes namespace [default: default]
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid setup

Interactive setup wizard for optimization features.

Generates and applies the Kubernetes resources needed for the requested optimization tiers.

Action Tiers: none - No automated actions (reporting only) restart - Can trigger pod restarts for recovery runtime - Can modify runtime parameters (batch size, etc.) full - Full automation including config updates and scaling

Analysis Tiers: core - Static analysis only (always available) enhanced - Adds live GPU info via NVML (requires device access) advanced - Full hardware verification via DCGM

Examples: lucid optimization setup lucid optimization setup --action-tier runtime --analysis-tier enhanced lucid optimization setup --dry-run lucid optimization setup --no-interactive -a restart -t core

Usage:

console $ lucid setup [OPTIONS]

Options:

  • -a, --action-tier TEXT: Action tier: none, restart, runtime, or full [default: none]
  • -t, --analysis-tier TEXT: Analysis tier: core, enhanced, or advanced [default: core]
  • -n, --namespace TEXT: Kubernetes namespace [default: default]
  • --dry-run: Show what would be applied without applying
  • --interactive / --no-interactive: Interactive mode [default: interactive]
  • --help: Show this message and exit.

lucid history

Show recent optimization changes.

Queries the operator for the history of applied optimization changes, including rollbacks and their outcomes.

Examples: lucid optimization history lucid optimization history -n production -l 50 lucid optimization history --json

Usage:

console $ lucid history [OPTIONS]

Options:

  • -n, --namespace TEXT: Kubernetes namespace [default: default]
  • -l, --limit INTEGER: Maximum number of entries [default: 20]
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid rollback

Manually rollback an optimization change.

Reverts a specific optimization change or the most recent one. This restores the previous configuration value and optionally triggers a pod restart if needed.

Examples: lucid optimization rollback --latest lucid optimization rollback --change-id abc123 lucid optimization rollback --latest -y

Usage:

console $ lucid rollback [OPTIONS]

Options:

  • -c, --change-id TEXT: Specific change ID to rollback
  • --latest: Rollback the most recent change
  • -n, --namespace TEXT: Kubernetes namespace [default: default]
  • -y, --yes: Skip confirmation
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid

List and view workspaces (read-only).

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • list: List workspaces.

lucid list

List workspaces.

Shows all workspaces you have access to. To create or manage workspaces, use the Observer UI: lucid open --settings

Usage:

console $ lucid list [OPTIONS]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid

Manage Lucid Auditors

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • init: Scaffold a new auditor project from...
  • dev: Start the local development server with...
  • test: Run contract compliance tests against an...
  • register: Register an auditor with the Lucid platform.
  • list: List all registered auditors for your...
  • schema: Show the detection-tuning schema for an...
  • verify: Verify an auditor image's contract and...
  • publish: Verify, sign, and push an auditor image.
  • settings: Manage auditor settings

lucid init

Scaffold a new auditor project from templates.

Creates a project directory with all the files needed to develop a custom Lucid auditor, including a FastAPI server, config, Dockerfile, and contract compliance tests.

The project name is used as the directory name and substituted into template placeholders.

Examples: lucid auditor init my-toxicity-auditor lucid auditor init pii-scanner --output ~/projects

Usage:

console $ lucid init [OPTIONS] NAME

Arguments:

  • NAME: Name for the new auditor project [required]

Options:

  • -o, --output PATH: Parent directory (defaults to current directory)
  • --help: Show this message and exit.

lucid dev

Start the local development server with hot reload.

By default, uses Docker Compose to spin up the auditor and a mock chain service. Use --no-docker to run directly with uvicorn if you prefer a lighter-weight setup.

The dev server watches for file changes and automatically reloads.

Examples: lucid auditor dev lucid auditor dev --dir ./my-auditor lucid auditor dev --no-docker --port 9000

Usage:

console $ lucid dev [OPTIONS]

Options:

  • -d, --dir PATH: Auditor project directory (defaults to current directory)
  • -p, --port INTEGER: Port to bind the dev server to [default: 8090]
  • --no-docker: Run directly with uvicorn instead of Docker Compose
  • --help: Show this message and exit.

lucid test

Run contract compliance tests against an auditor.

Tests can either be run against a live URL (default: localhost:8090) or by executing the project's pytest suite.

When targeting a URL, the following contract checks are performed: 1. Health endpoint returns 200 with required fields 2. Claims endpoint accepts valid payload and returns list[Claim]

Examples: lucid auditor test lucid auditor test --url http://my-auditor:8090 lucid auditor test --dir ./my-auditor lucid auditor test --json

Usage:

console $ lucid test [OPTIONS]

Options:

  • -u, --url TEXT: Base URL of the running auditor [default: http://localhost:8090]
  • -d, --dir PATH: Run pytest on project's tests/ directory instead
  • --json: Output results as JSON
  • --help: Show this message and exit.

lucid register

Register an auditor with the Lucid platform.

Registers a custom auditor endpoint with the Auditor Registry so it can participate in the VAP audit chain. The Verifier will perform an initial health check during registration.

Use --mode shadow to test your auditor alongside production auditors without affecting decisions. Use --mode active when ready for production.

Use --claims to register the claim vocabulary produced by this auditor. This enables Cedar policies to reference specific claim names.

Examples: lucid auditor register --id my-auditor --name "My Auditor" --endpoint https://auditor.internal:8090 lucid auditor register --id pii-scanner --name "PII Scanner" --endpoint http://pii:8090 --mode active lucid auditor register --id tee-auditor --name "TEE Auditor" --endpoint https://tee:8090 --deployment-mode sidecar --image-digest sha256:abc lucid auditor register --id toxicity --name "Toxicity" --endpoint http://tox:8090 --claims toxicity.score,toxicity.label

Usage:

console $ lucid register [OPTIONS]

Options:

  • --id TEXT: Unique auditor identifier [required]
  • -n, --name TEXT: Display name [required]
  • -e, --endpoint TEXT: Auditor endpoint URL [required]
  • -d, --deployment-mode TEXT: Deployment mode: sidecar, in_cluster, or external [default: external]
  • --auth-type TEXT: Auth type: mtls, bearer, or api_key [default: api_key]
  • -m, --mode TEXT: Registration mode: shadow or active [default: shadow]
  • --description TEXT: Auditor description
  • --phases TEXT: Comma-separated supported phases (request,response,data_retrieval)
  • --image-digest TEXT: Container image digest for TEE attestation
  • --claims TEXT: Comma-separated claim vocabulary (e.g., 'toxicity.score,toxicity.label')
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid list

List all registered auditors for your organization.

Displays auditor ID, name, deployment mode, trust tier, status, and current health.

Examples: lucid auditor list lucid auditor list --json

Usage:

console $ lucid list [OPTIONS]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid schema

Show the detection-tuning schema for an auditor.

Displays the available detection-tuning fields, their types, defaults, and groupings. This information is used by the Observer UI to auto-generate settings panels. Enforcement is managed via Cedar policies, not per-field settings.

Examples: lucid auditor schema lucid-llm-judge-auditor lucid auditor schema lucid-llm-judge-auditor --json

Usage:

console $ lucid schema [OPTIONS] AUDITOR_ID

Arguments:

  • AUDITOR_ID: Auditor ID to show schema for [required]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid verify

Verify an auditor image's contract and labels.

This command performs a 'compliance probe' on a local container image to ensure it meets the Lucid Auditor Standard. It checks: 1. OCI Labels: Required metadata like fields, version, and phase. 2. API Contract: Starts an ephemeral instance and probes /health and /claims.

Args: image: The tag of the local Docker image to verify (e.g., 'compliance-auditor:v1').

Usage:

console $ lucid verify [OPTIONS] IMAGE

Arguments:

  • IMAGE: [required]

Options:

  • --help: Show this message and exit.

lucid publish

Verify, sign, and push an auditor image.

This is the primary way to release an Auditor to the Lucid network. It performs the following steps: 1. Verify: Runs the lucid auditor verify suite. 2. Sign: Calculates the image digest and signs it using the API key (HMAC). 3. Push: Uploads the image to the specified container registry. 4. Notarize: Registers the signed digest with the centralized Verifier service.

Args: image: The local image tag to publish. registry: The target container registry (e.g., 'ghcr.io/my-org'). If not provided, skips the push step and only notarizes.

The API key is read from the LUCID_API_KEY environment variable, or prompted interactively if not set.

Usage:

console $ lucid publish [OPTIONS] IMAGE

Arguments:

  • IMAGE: [required]

Options:

  • --registry TEXT
  • --help: Show this message and exit.

lucid settings

Manage auditor settings

Usage:

console $ lucid settings [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • get: Get auditor settings at a specific scope.
  • set: Set auditor settings at a specific scope.

lucid settings get

Get auditor settings at a specific scope.

Retrieves the raw settings for an auditor at the given scope level (org, workspace, or agent). Use this to inspect settings before making changes.

For the resolved effective configuration (with cascade), use the Observer UI or the API directly.

Examples: lucid auditor settings get lucid-llm-judge-auditor --scope org --scope-id lucid auditor settings get lucid-llm-judge-auditor --scope workspace --scope-id --json

Usage:

console $ lucid settings get [OPTIONS] AUDITOR_ID

Arguments:

  • AUDITOR_ID: Auditor ID [required]

Options:

  • -s, --scope TEXT: Scope: org, workspace, or agent [required]
  • --scope-id TEXT: UUID of the scope entity [required]
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid settings set

Set auditor settings at a specific scope.

Creates or updates the auditor settings at the given scope level. Settings can be provided as a JSON string or from a JSON file.

Settings at lower scopes (agent) override higher scopes (workspace, org). Enforcement is handled by Cedar policies, not by individual settings.

Examples: lucid auditor settings set lucid-llm-judge-auditor --scope org --scope-id --settings '{"jailbreak_detection": true}' lucid auditor settings set lucid-llm-judge-auditor --scope workspace --scope-id -f settings.json

Usage:

console $ lucid settings set [OPTIONS] AUDITOR_ID

Arguments:

  • AUDITOR_ID: Auditor ID [required]

Options:

  • -s, --scope TEXT: Scope: org, workspace, or agent [required]
  • --scope-id TEXT: UUID of the scope entity [required]
  • --settings TEXT: Settings as JSON string
  • -f, --file PATH: Path to JSON file with settings
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid

Manage model registrations

Usage:

console $ lucid [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • register: Register a self-hosted model with the...
  • list: List all registered models for your...
  • verify: Verify a model's TEE attestation.
  • test: Run compliance tests against a registered...

lucid register

Register a self-hosted model with the Lucid platform.

The model endpoint must be an OpenAI-compatible inference API. After registration, the Verifier will perform an initial health check to confirm connectivity.

Examples: lucid model register --id my-llama --name "Llama 3" --endpoint https://llama.internal:8080/v1 lucid model register --id embedding-v1 --name "Embedder" --endpoint http://embed:8080/v1 --type embedding lucid model register --id secure-model --name "TEE Model" --endpoint https://tee:8080/v1 --deployment-mode sidecar --image-digest sha256:abc123

Usage:

console $ lucid register [OPTIONS]

Options:

  • --id TEXT: Unique model identifier [required]
  • -n, --name TEXT: Display name [required]
  • -e, --endpoint TEXT: Model inference endpoint URL [required]
  • -t, --type TEXT: Model type: chat, completion, or embedding [default: chat]
  • -d, --deployment-mode TEXT: Deployment mode: sidecar, in_cluster, or external [default: external]
  • --auth-type TEXT: Auth type: mtls, bearer, or api_key [default: api_key]
  • --description TEXT: Model description
  • --context-window INTEGER: Context window size in tokens
  • --image-digest TEXT: Container image digest for TEE attestation
  • --json: Output as JSON
  • --help: Show this message and exit.

lucid list

List all registered models for your organization.

Displays model ID, name, type, deployment mode, trust tier, and current health status.

Examples: lucid model list lucid model list --json

Usage:

console $ lucid list [OPTIONS]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid verify

Verify a model's TEE attestation.

Requests the Verifier to perform remote attestation verification against the model endpoint. If verification succeeds, the model's trust tier is upgraded to 'tee_attested'.

This command is only meaningful for models deployed in TEE environments (sidecar deployment mode with an image digest).

Examples: lucid model verify my-llama lucid model verify secure-model --json

Usage:

console $ lucid verify [OPTIONS] MODEL_ID

Arguments:

  • MODEL_ID: Model ID to verify [required]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.

lucid test

Run compliance tests against a registered model.

Performs the following checks: 1. Model exists in the registry 2. Health check passes (endpoint is reachable) 3. Model responds to a test inference request 4. Response format is OpenAI-compatible

Examples: lucid model test my-llama lucid model test secure-model --json

Usage:

console $ lucid test [OPTIONS] MODEL_ID

Arguments:

  • MODEL_ID: Model ID to test [required]

Options:

  • --json: Output as JSON
  • --help: Show this message and exit.