CLI reference

The alquimia CLI is the primary way to manage agentspaces, agent specs, tools, models, topics, files, secrets, and OCI artifacts from the terminal.

Global options

All commands respect these environment variables and options:

Variable	Default	Description
`ALQUIMIA_REGISTRY_DIR`	—	Root directory for local TinyDB registries
`--namespace` / `-n`	`default`	Agentspace to operate on
`--fields` / `-f`	all	Comma-separated field list for list commands
`--debug`	`false`	Enable verbose logging

Top-level commands

Command	Description
`alquimia registry ...`	Manage agentspaces and their contents
`alquimia explore ...`	List repositories and tags in a remote OCI registry
`alquimia local ...`	Run local chat sessions and inspect history
`alquimia code ...`	Alquimia Code TUI (when available)

`alquimia registry`

Repository lifecycle

Command	Description
`alquimia registry create`	Create a new agentspace
`alquimia registry list`	List local agentspaces
`alquimia registry inspect`	Show agentspace metadata
`alquimia registry destroy`	Delete an agentspace and all contents
`alquimia registry publish`	Push an agentspace to OCI
`alquimia registry unpublish`	Remove an OCI manifest
`alquimia registry pull`	Pull an agentspace from OCI and overwrite local `dist.json`
`alquimia registry fetch --tag <tag> [--no-cache]`	Pull an OCI tag into a cached versioned snapshot (0.5.2+)
`alquimia registry versions`	List cached versioned snapshots (0.5.2+)
`alquimia registry flush-version <tag>`	Remove a cached versioned snapshot (0.5.2+)

`registry create`

alquimia registry create \
  --name production \
  --namespace production \
  --tag latest \
  --user-id alice \
  --description "Production support agents"

`registry publish`

alquimia registry publish --namespace production --tag v1.2.0

Add --include-secrets to also push secret metadata (not values) as a private layer.

Agents

Command	Description
`alquimia registry agents add <path>`	Import an agent from JSON
`alquimia registry agents list`	List agents
`alquimia registry agents inspect <assistant_id>`	Show full spec

alquimia registry agents add support-bot.json --namespace default
alquimia registry agents inspect support-bot --namespace default

Secrets

Command	Description
`alquimia registry secrets add <key>`	Register a secret definition
`alquimia registry secrets put <key> <value>`	Store a value in the resolver
`alquimia registry secrets list`	List secret definitions

alquimia registry secrets add RESPONSE_PROVIDER_API_KEY \
  --scope shared --required

alquimia registry secrets put RESPONSE_PROVIDER_API_KEY sk-xxx

Parameters

Command	Description
`alquimia registry parameters add <key>`	Register a parameter
`alquimia registry parameters list`	List parameters

alquimia registry parameters add SUPPORT_TIER \
  --default L1 --assistant-id support-bot \
  --description "Support escalation tier"

Tools

Command	Description
`alquimia registry tools add <registered_tool_id>`	Register a tool connection
`alquimia registry tools list`	List tool registrations
`alquimia registry tools inspect <registered_tool_id>`	Show registration
`alquimia registry tools set-operation <tool_id> <name>`	Classify one operation

alquimia registry tools add filesystem-tools \
  --provider-id mcp \
  --connection-config '{"url": {"$secretRef": "MCP_PROVIDER_URL"}}'

alquimia registry tools set-operation filesystem-tools "delete_*" \
  --match glob \
  --severity destructive \
  --tier-grants operator \
  --approval-required

Models

Command	Description
`alquimia registry models add <registered_model_id>`	Register a reusable model
`alquimia registry models list`	List model registrations

alquimia registry models add gpt-4o-mini \
  --provider-id openai \
  --params '{"model": "gpt-4o-mini", "temperature": 0.0}'

Topics and files

Command	Description
`alquimia registry topics add <topic_id>`	Register a knowledge topic
`alquimia registry topics list`	List topics
`alquimia registry topics inspect <topic_id>`	Show topic registration
`alquimia registry topics set-policy <topic_id>`	Update access policy
`alquimia registry topics add-file <topic_id>`	Upload and index a file
`alquimia registry topics remove-file <topic_id> <file_id>`	Remove a file
`alquimia registry topics rebuild <topic_id>`	Re-index all files
`alquimia registry files list`	List file registrations
`alquimia registry files inspect <file_id>`	Show file metadata
`alquimia registry files read <file_id>`	Download bytes

alquimia registry topics add product-docs \
  --severity read-only \
  --tier-grants reader,editor,operator

alquimia registry topics add-file product-docs release-notes.pdf \
  --hydrate --provider qdrant

Boltzmann brains

Command	Description
`alquimia registry brains add <brain_id>`	Register a brain
`alquimia registry brains list`	List brains
`alquimia registry brains inspect <brain_id>`	Show brain registration
`alquimia registry brains set-policy <brain_id> <memory_type>`	Set module access

Requires the optional boltzmann extra.

`alquimia explore`

Command	Description
`alquimia explore repos`	List repositories in a remote OCI registry
`alquimia explore tags <repo_id>`	List tags for a repository

alquimia explore repos --registry ghcr.io/acme/alquimia
alquimia explore tags ghcr.io/acme/alquimia/production

`alquimia local`

Run one-off or interactive chat sessions with agents from the local registry. Available only when the local-chat extra is installed. As of alquimia-core 0.5.2, chat and exec accept a versioned reference so you can run a specific OCI tag without changing the workspace dist.json.

Command	Description
`alquimia local chat <agentspace>/<assistant>[:<tag>]`	Start an interactive session
`alquimia local exec <agentspace>/<assistant>[:<tag>] <query>`	Single-turn inference (0.5.2+)
`alquimia local run <assistant_id> <query>`	Single-turn inference against the local workspace
`alquimia local sessions`	List local sessions

# Chat against the local workspace
alquimia local chat default/support-bot --mcp-servers mcp.json

# Run a specific OCI-tagged version without mutating dist.json
alquimia local exec production/support-bot:v1.2.0 "What is the refund policy?"
alquimia local chat production/support-bot:v1.2.0 --no-cache

Common patterns

Promote an agentspace from staging to production

alquimia registry publish --namespace staging --tag v1.0.0
alquimia registry pull --namespace production \
  --oci-reference ghcr.io/acme/alquimia/staging --tag v1.0.0
alquimia registry topics rebuild product-docs --namespace production

Run a versioned agentspace without changing the workspace

alquimia registry fetch --namespace myspace --tag v1.2.0
alquimia local exec myspace/support-bot:v1.2.0 "What is the refund policy?"

Classify every operation on an MCP server

alquimia registry tools inspect filesystem-tools --for-tool "delete_file"
alquimia registry tools set-operation filesystem-tools "delete_*" \
  --match glob --severity destructive --tier-grants operator

Register a model and use it in an agent

alquimia registry models add gpt-4o-mini --provider-id openai \
  --params '{"model": "gpt-4o-mini", "temperature": 0.0}'
# Then reference `model_ref: gpt-4o-mini` in the agent spec

Help from the terminal

Every command and subcommand supports --help:

alquimia --help
alquimia registry tools set-operation --help
alquimia registry topics add-file --help