Cadenza CLI Reference

Authenticate with an API token and store credentials locally. Tokens must start with evodb_sk_. If --token is omitted, you'll be prompted interactively.

cadenza login --token evodb_sk_your_token_here

Display the current authentication status and configured API endpoint. Shows a token prefix and the base URL.

cadenza status
# token: evodb_sk_abc12...
# endpoint: https://api.myluca.ai

Remove locally stored credentials by deleting ~/.cadenza/config.toml.

Get or set configuration values using dot-notation keys. Three usage modes:

cadenza config

cadenza config defaults.project

cadenza config defaults.project my-project

List all projects accessible with the current API token.

cadenza projects
# NAME          SLUG            CREATED
# my-project    my-project      2025-01-15

Show the active genotype and its behavioral dimensions for a project. Behavioral dimensions define the axes of the search space.

cadenza genotype -p my-project

List all islands (subpopulations) and their population statistics for a project.

cadenza islands -p my-project
# ISLAND                DESCRIPTION                     PHENOTYPES
# learning-rates        Explores LR schedules           42
# architectures         Different model architectures    28

List experiments within a specific island, with pagination. Returns 10 experiments per page.

cadenza experiments -i learning-rates -p my-project --page 2

Show the elite archive — the top-performing experiments across all islands. Each elite includes fitness scores and behavioral coordinates.

cadenza elites -p my-project

Generate a compact LLM-ready JSON context snapshot. This is the primary command for AI agent consumption — it combines the genotype, island summaries, and top elites into a single JSON output.

cadenza sample -p my-project --top-phenotypes 5
# Outputs compact JSON:
# {"genotype":{...},"islands":[...],"elite_archive":[...]}

Start importing a W&B project into the evolutionary database. Requires wandb.entity and wandb.api-key to be configured first.

Optional EvoDB tuning parameters from config are applied automatically: evodb.max-dimensions, evodb.elite-archive-size, evodb.max-islands.

# Configure W&B first
cadenza config wandb.entity my-team
cadenza config wandb.api-key wand_abc123...

# Import a project
cadenza import my-wandb-project

List all import jobs and their status. Possible statuses: queued | running | completed | failed.

cadenza import list

Add a single W&B run to an existing project. This is useful for incrementally ingesting new runs without re-importing an entire project. Requires wandb.entity and wandb.api-key to be configured first.

# Add a single run to the default project
cadenza add --run_id abc123def

# Add a run to a specific project
cadenza add --run_id abc123def -p my-project --wandb-project my-wandb-project

Output the full command schema as machine-readable JSON. Designed for agent self-discovery — an AI agent can call this to learn all available commands, their arguments, and descriptions.

cadenza schema
# {"commands":[{"name":"login","description":"...","args":[...]},...],"auth":"..."}