Skip to content

Lucid CLI Reference

The Lucid CLI (lucid) provides commands for deploying and managing AI agents, browsing the app 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, OpenClaw, 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 a LucidEnvironment 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 app catalog
lucid passport View AI passports
lucid auditor Verify and publish auditor images
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)

URL Resolution

The Observer URL is resolved with this precedence: 1. LUCID_OBSERVER_URL environment variable 2. observer_url in ~/.lucid/config.yaml 3. http://localhost:5173 (dev context) or https://observer.lucid.engineering (prod context)

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 (apps, models, auditor profiles).

Subcommand Description
lucid catalog apps List apps in the catalog
lucid catalog models List models available in the serverless catalog
lucid catalog auditors List auditor profiles
lucid catalog show <app-id> Show details for a catalog app

lucid catalog apps

List apps in the catalog.

lucid catalog apps [--category CATEGORY] [--verified] [--json]

Options: - -c, --category CATEGORY - Filter by category - --verified - Show only verified apps - --json - Output as JSON

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 catalog show

Show details for a catalog app.

lucid catalog show <app-id> [--json]

Options: - --json - Output as JSON

lucid auditor

Verify and publish auditor images.

Subcommand Description
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 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>

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

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]

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.

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

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 agent spec - --json - Output as JSON

Examples: 

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

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

Supports LucidEnvironment, LucidWorkspace, and LucidPolicy 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, LucidPolicy). 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

Stop a running agent.

Examples: lucid stop 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

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

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

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:

  • verify: Verify an auditor image's contract and...
  • publish: Verify, sign, and push an auditor image.

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

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

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.

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

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.