CLI Tools¶

Latent provides a command-line interface for common development tasks.

Installation¶

The CLI is available after installing Latent:

pip install latent

The base install is minimal. version, scaffold, init, config, vendor, and agents work without extras. The flow commands — list/flows, run, graph, validate, metrics, chat, optimize — require the eval extra and exit with an error if it is missing:

pip install "latent[eval]"

(chat additionally needs the chat extra, and optimize needs optimizers.)

Or add it to your pyproject.toml:

[project.scripts]
latent = "latent.cli:main"

Available Commands¶

Command	Description	Requires
`latent version`	Show latent-py version and check compatibility	—
`latent scaffold`	Scaffold a new project (config + version pin + `global.yaml` + `.env.example`)	—
`latent init`	Generate a config file (`config/latent.toml`)	—
`latent config`	Show current configuration	—
`latent vendor`	Vendor latent subpackages into a consumer repo	—
`latent list` (alias `latent flows`)	List discovered flows with parameters and metadata	`[eval]`
`latent run`	Execute a flow with CLI flags overriding parameters.yaml	`[eval]`
`latent validate`	Validate catalog schemas and paths	`[eval]`
`latent graph`	Visualize pipeline topology	`[eval]`
`latent metrics`	Show MLflow metrics	`[eval]`
`latent clean`	Clean cache, logs, and temporary files	—
`latent agents`	List discovered agents	—
`latent chat`	Start an interactive chat session with an agent	`[eval]`, `[chat]`
`latent optimize`	Run an optimization flow	`[eval]`, `[optimizers]`
`latent infra`	Manage local infrastructure (PostgreSQL, Prefect, MLflow)	—
`latent studio`	Interact with Agent Studio datasets and conversations	—
`latent autoresearch`	Autonomous code optimization via the AutoResearch loop	—

Commands¶

`latent version`¶

Show the installed latent-py version:

# Print the installed version
latent version

# Check the installed version against the project pin
latent version --check

Options:

Flag	Description
`--check`	Check the pinned (`[tool.latent-py].version`) vs. installed version; exits non-zero if incompatible

`latent scaffold`¶

Scaffold a new latent-py project. Creates the standard project files (skipping any that already exist):

# Scaffold the current directory
latent scaffold

# Scaffold a new project directory
latent scaffold ./my-eval-project
latent scaffold project my-eval-project

A bare latent scaffold PATH routes to this command only for a PATH that cannot be a verb: ., .., a path containing a separator, or a directory that already exists. A bare name that is not a directory yet is a usage error — it is a typo (latent scaffold flwo) at least as often as a target — so spell out the project verb, or write the path as ./my-eval-project.

This writes:

[tool.latent-py].version pin in pyproject.toml
config/latent.toml — framework configuration
<flows_dir>/global.yaml — shared pipeline defaults
.env.example — environment variable template

scaffold vs init

Use latent scaffold to set up a whole project. Use latent init when you only need the config/latent.toml file (e.g. adding config to an existing project) — see below.

`latent init`¶

Generate a config/latent.toml configuration file (only the config file — for full project setup use latent scaffold):

# Create config/latent.toml (default location)
latent init

# Create at custom path
latent init --output my-config.toml

# Overwrite existing file
latent init --force

Options:

Flag	Description
`--output`, `-o`	Path for the config file (default: `config/latent.toml`)
`--force`, `-f`	Overwrite existing config file

This generates a fully documented configuration file with all available options:

config/latent.toml

[workspace]
# flows_dir = "flows"
# data_dir = "data"
# logs_dir = "logs"
# mlruns_dir = "mlruns"

[mlflow]
enabled = true
litellm_autolog = true

[logging]
level = "INFO"

See Workspace Configuration for full details on configuration options.

`latent config`¶

Show the current configuration (merged from TOML and environment variables):

# Pretty-printed output
latent config

# JSON format (machine-readable)
latent config --format json

# TOML format
latent config --format toml

# Include default values
latent config --show-defaults

Options:

Flag	Description
`--format`, `-f`	Output format: `pretty` (default), `json`, or `toml`
`--show-defaults`, `-d`	Show default values for unset options

Output:

Latent Configuration
============================================================

Config file: /path/to/config/latent.toml

Environment:
  Mode                 production                          [toml]

Workspace:
  Root                 /path/to/project                    [default]
  Flows Dir            /path/to/project/flows              [default]
  Data Dir             /path/to/project/data               [default]

MLflow:
  Enabled              true                                [toml]
  Litellm Autolog      true                                [toml]

Logging:
  Level                INFO                                [default]

============================================================

Legend: [env] = Environment variable, [toml] = Config file, [default] = Default

`latent list`¶

List discovered flows with parameters and metadata:

# List all flows
latent list

# Show details for a specific flow
latent list my_flow

The detailed view shows the flow's parameters, types, defaults, and catalog files.

latent flows is an alias for latent list.

`latent run`¶

Execute a flow with CLI flags overriding parameters.yaml:

# Run a flow
latent run my_flow

# Override parameters via CLI flags
latent run my_flow --model openai/gpt-4o --sample-size 100

# Show flow parameters
latent run my_flow --help

Extra flags are parsed and matched against the flow's parameter definitions. Underscores and hyphens are interchangeable (--sample-size and --sample_size both work).

Note

latent run automatically loads .env files and applies latent infra connection state (if running) before executing the flow.

`latent validate`¶

Validate catalog schemas and paths:

# Validate all flows
latent validate

# Validate a specific flow
latent validate my_flow

Note

The former spelling latent check is a hidden alias for one release and prints a deprecation notice on stderr. check now means one thing across the CLI — run a quality gate and exit non-zero when it fails (latent lint check, latent thresholds check).

Output:

Checking flow: data_pipeline
  parameters.yaml found
  catalog.yaml found
  Found 3 dataset(s)
    - raw_data (pandas.CSV)
    - cleaned_data (pandas.CSV)
      Schema validated: my_app.schemas.CleanedDataSchema
    - processed_data (pandas.Parquet)
      Schema validated: my_app.schemas.ProcessedDataSchema
  Flow check complete

What it checks:

parameters.yaml exists
catalog.yaml exists
Catalog datasets are well-formed
Schema paths are importable
Dataset types are valid

`latent graph`¶

Visualize your pipeline topology:

latent graph

Output:

=== Pipeline Topology ===

Flow: data_pipeline
  +-- load_data
  |    out: raw_data
  +-- clean_data
  |    in: raw_data
  |    out: cleaned_data
  +-- process_data
  |    in: cleaned_data
  |    out: processed_data

Flow: evaluation
  +-- load_results
  |    in: data_pipeline.processed_data
  |    out: results
  +-- analyze
  |    in: results
  |    out: analysis

Note

The registry is populated when flows are imported. latent graph force-imports all discovered flows to populate the task registry.

`latent metrics`¶

Show evaluation metrics from MLflow:

# List all experiments
latent metrics

# Show metrics for a specific flow
latent metrics my_flow

Output (listing experiments):

Available experiments:

  data_pipeline (5 runs)
  evaluation (3 runs)
  training (12 runs)

Output (specific flow):

Metrics for flow: evaluation

Total runs: 3
Latest run: 2024-01-15 14:30:00

Metrics from latest run:
  accuracy: 0.9523
  f1_score: 0.9412
  latency: 2.3400

`latent clean`¶

Clean cache, logs, and temporary files:

# Clean Prefect cache only
latent clean --cache

# Clean everything (cache, logs, mlruns)
latent clean --all

Options:

Flag	Description
`--cache`	Clean Prefect task cache (`.prefect/` directory)
`--all`	Clean cache + logs + MLflow runs

`latent agents`¶

List discovered agents with parameters and metadata:

# List all agents
latent agents

# Show details for a specific agent
latent agents my_agent

Agents are discovered via the [agents] scan_paths configuration in latent.toml. The detailed view shows constructor parameters, types, and defaults.

`latent chat`¶

Start an interactive chat session with an agent:

# Start a new chat session
latent chat my_agent

# Resume a previous session
latent chat my_agent --session abc123

# Override constructor parameters
latent chat my_agent --model openai/gpt-4o

# Show agent parameters
latent chat my_agent --help

Options:

Flag	Description
`--session`	Resume a session by ID

Extra flags are passed as constructor parameters to the agent.

Info

Requires the [chat] extra: pip install "latent[chat]"

`latent optimize`¶

Run an optimization flow:

# Run an optimization flow
latent optimize my_optimize_flow

# Override parameters
latent optimize my_optimize_flow --model openai/gpt-4o

# Show flow parameters
latent optimize my_optimize_flow --help

The target flow must be tagged with optimize in its @flow decorator. Extra flags are passed through as parameter overrides.

Info

Requires the [eval] and [optimizers] extras: pip install "latent[eval]" "latent[optimizers]"

`latent vendor`¶

Vendor latent subpackages into a consumer repo. Two modes are available:

Package mode (default) copies whole subpackages.
Import-graph mode (--from) copies only the transitive closure of latent.* imports starting from .py files under each given directory.

# Package mode: vendor agents and chat into another repo
latent vendor ../my-app --packages agents chat

# List available packages
latent vendor --list

# Vendor to a custom directory
latent vendor ../my-app --packages agents --vendor-dir lib

# Skip pyproject.toml patching
latent vendor ../my-app --packages agents --no-pyproject

# Import-graph mode: copy only what's actually imported
latent vendor ../my-app --from ../my-app/apps/web --from ../my-app/libs/sdk

# Drift check (CI): fail if the on-disk vendor differs from the import-graph closure
latent vendor ../my-app --from ../my-app/apps/web --check

Options:

Flag	Description
`--packages`, `-p`	Comma or space-separated subpackages to vendor (default: `agents`). Ignored when `--from` is given.
`--from`, `-f`	Import-graph mode: copy only what is transitively imported by `.py` files under this dir. Repeatable. Resolved relative to the target when not absolute.
`--vendor-dir`	Vendor directory name inside the target repo (default: `vendor`)
`--no-pyproject`	Skip patching the target repo's `pyproject.toml`
`--list`	List available packages and exit
`--check`	Drift mode: compare the on-disk vendor against the import-graph closure for the given `--from` dirs; exits non-zero if they differ. Requires at least one `--from`.

Available packages: agents, chat, guardrails, stats, scores. Transitive dependencies are resolved automatically.

`latent infra`¶

Manage local infrastructure services (PostgreSQL, Prefect, MLflow). See the Infrastructure page for full details.

latent infra up              # Start all services (foreground)
latent infra up -d           # Start all services (background)
latent infra up postgres     # Start specific service
latent infra down            # Stop all services
latent infra down -v         # Stop and remove data volumes
latent infra status          # Show service health
latent infra logs            # Show logs (last 50 lines)
latent infra logs prefect -f # Follow specific service logs
latent infra env             # Print connection env vars

`latent studio`¶

Interact with Agent Studio datasets and conversations. This is a sub-CLI with two command groups: datasets and conversations.

`latent studio datasets`¶

# List available datasets (optionally filter by type)
latent studio datasets ls
latent studio datasets ls --type conversation --limit 20 --json

# Download a dataset (defaults to the latest version)
latent studio datasets download my_dataset
latent studio datasets download my_dataset --version 3 --output ./data
latent studio datasets download my_dataset --csv      # force CSV
latent studio datasets download my_dataset --jsonl    # force JSONL

# Create an empty dataset (one-time setup before the first upload)
latent studio datasets create eval-results \
  --display-name "Eval Results" --type generic --description "..."

# Upload a JSONL file as a new published version
latent studio datasets upload results.jsonl --slug eval-results
latent studio datasets upload results.jsonl --slug eval-results --tag production --exclusive

# Tag / untag a specific version
latent studio datasets tag eval-results --version 3 --tag production --exclusive
latent studio datasets untag eval-results --version 3 --tag production

# Promote a version (exclusive tag, default 'production')
latent studio datasets promote eval-results --version 3

Dataset types: conversation, qa_pair, generic, file_bundle. Sources: upload, curated, disk, mixed.

`latent studio conversations`¶

# List conversations with filters
latent studio conversations ls --mode conversation --feedback good --min-score 4
latent studio conversations ls --from 2026-04-01 --to 2026-05-01 --json

# Download conversations as JSONL with full message content
latent studio conversations download --output ./data
latent studio conversations download --mode qa --feedback bad --limit 1000

Filters: --mode (qa, conversation, all), --from/--to (ISO 8601 dates), --feedback (good, bad, any, none), --min-score/--max-score (1-5), --limit.

`latent autoresearch`¶

Autonomous code optimization via the AutoResearch loop. This is a sub-CLI with its own commands.

`latent autoresearch run`¶

Launch the AutoResearch optimizer loop:

# Run with config file
latent autoresearch run --config autoresearch/parameters.yaml \
  --entrypoint pipelines/autoresearch/eval_flow.py:autoresearch_eval_flow

# Override iterations
latent autoresearch run -e pipelines/autoresearch/eval_flow.py:autoresearch_eval_flow -n 50

# Resume from latest tracker
latent autoresearch run -e pipelines/autoresearch/eval_flow.py:autoresearch_eval_flow --resume

Options:

Flag	Description
`--config`, `-c`	Path to `parameters.yaml`
`--entrypoint`, `-e`	Entrypoint as `path/to/file.py:function_name`
`--source`, `-s`	Source directory for entrypoint imports
`--deployment`, `-d`	Prefect deployment name
`--pool`	Prefect work pool name (default: `autoresearch-pool`)
`--max-iterations`, `-n`	Override max iterations (default: 50)
`--sample-size`	Override sample size (default: 150)
`--checkpoint`	Path to a specific tracker checkpoint
`--resume`, `--latest`	Resume from most recent tracker

`latent autoresearch status`¶

Show current AutoResearch run status from the tracker file:

# One-shot status (auto-discovers latest tracker)
latent autoresearch status

# Status for a specific tracker
latent autoresearch status data/autoresearch/output/2024-01-15.tracker.json

# Watch mode with live updates
latent autoresearch status --watch
latent autoresearch status -w

Options:

Flag	Description
`--watch`, `-w`	Watch mode — re-render the status in place, picking up tracker changes as the run progresses (Ctrl-C to exit)

Usage in CI/CD¶

Validate Flows¶

# .github/workflows/validate.yml
name: Validate Flows

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install "latent[eval]"
      - run: latent validate

Generate Pipeline Visualization¶

# .github/workflows/docs.yml
name: Generate Docs

on: [push]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install "latent[eval]"
      - run: latent graph > pipeline.txt
      - uses: actions/upload-artifact@v4
        with:
          name: pipeline-topology
          path: pipeline.txt

Programmatic Usage¶

You can also use CLI functions programmatically:

from latent.cli import _check_flow
from latent.registry import TaskRegistry

# Check a flow
_check_flow("my_flow")

# Print topology
TaskRegistry.print_ascii()

CLI Tools¶

Installation¶

Available Commands¶

Commands¶

latent version¶

latent scaffold¶

latent init¶

latent config¶

latent list¶

latent run¶

latent validate¶

latent graph¶

latent metrics¶

latent clean¶

latent agents¶

latent chat¶

latent optimize¶

latent vendor¶

latent infra¶

latent studio¶

latent studio datasets¶

latent studio conversations¶

latent autoresearch¶

latent autoresearch run¶

latent autoresearch status¶

Usage in CI/CD¶

Validate Flows¶

Generate Pipeline Visualization¶

Programmatic Usage¶

See Also¶

`latent version`¶

`latent scaffold`¶

`latent init`¶

`latent config`¶

`latent list`¶

`latent run`¶

`latent validate`¶

`latent graph`¶

`latent metrics`¶

`latent clean`¶

`latent agents`¶

`latent chat`¶

`latent optimize`¶

`latent vendor`¶

`latent infra`¶

`latent studio`¶

`latent studio datasets`¶

`latent studio conversations`¶

`latent autoresearch`¶

`latent autoresearch run`¶

`latent autoresearch status`¶