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
ALQUIMIA_OCI_SUBPROCESS_TIMEOUT	120	Ceiling (seconds) on any single oras/cosign invocation (0.5.5+)
--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 [--target <repo_id>] [--tag <tag>] [--no-cache]	Pull from OCI; without --tag overwrites dist.json, with --tag caches a 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+)
alquimia registry index ensure	Create the namespace index anchor (0.5.3+)
alquimia registry index status	Show index health and unhealed publish errors (0.5.3+)
alquimia registry index reindex	Re-attach index entries for locally known publishes (0.5.3+)
alquimia registry index prune	Detach index entries whose artifact is gone (0.5.3+)
alquimia registry index migrate	Move a pre-0.5.3 artifact to the new namespace path (0.5.3+)

registry create

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

As of alquimia-core 0.5.3, registry create only accepts --name, --tag, --user-id, --description, and --source-repo-id. The --namespace flag has been removed.

registry publish

# Publish the whole agentspace to its canonical deployment path
alquimia registry publish --namespace production --tag v1.2.0

# Publish to an alternate target repository
alquimia registry publish --namespace production --target oci.example.com/agents/production

# Publish only a subset of agents and the resources they reach
alquimia registry publish --namespace production \
  --include-agents onboarder,closer \
  --exclude-agents deprecated-bot

# Also push secret metadata (not values) as a private layer
alquimia registry publish --namespace production --include-secrets

As of alquimia-core 0.5.5, publish supports:

Flag	Description
--tag	OCI tag to publish under (defaults to the agentspace’s current tag).
--target	Override the target OCI repository. Must include a repository name.
--include-agents	Comma-separated assistant_ids to include. Only those agents and the tools, topics, files, models, brains, parameters, and secrets reachable from them are published.
--exclude-agents	Comma-separated assistant_ids to exclude (applied after --include-agents).
--include-secrets	Also push secret metadata (not values) as a private layer
--force	Take over a tag published by a different author

When --include-agents or --exclude-agents is used, the publish is filtered to the selected agents and their transitive resources. The unused-secret guard is skipped during subset publishes so that intentionally omitted agents do not trigger false positives.

registry unpublish

alquimia registry unpublish --namespace production --tag v1.2.0 accepts --target to remove a manifest from a specific repository.

# Remove a published manifest from the canonical path
alquimia registry unpublish --namespace production --tag v1.2.0

# Remove from an alternate target repository
alquimia registry unpublish --namespace production --tag v1.2.0 \
  --target oci.example.com/agents/production

registry index

alquimia registry index ensure
alquimia registry index status
alquimia registry index reindex --namespace production --dry-run
alquimia registry index prune --dry-run
alquimia registry index migrate -n production

As of alquimia-core 0.5.5, registry index reindex no longer prints a bare 0 when nothing is reindexed. It prints a summary of repositories visited, namespace-filter mismatches, and brain namespace mismatches. Agentspace load failures are logged and cause the command to exit non-zero.

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 get <key>	Show the resolved value
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

# Store a per-user override for a shared or local secret
alquimia registry secrets put RESPONSE_PROVIDER_API_KEY sk-alice-xxx \
  --user-id alice

alquimia registry secrets get RESPONSE_PROVIDER_API_KEY --user-id alice

As of alquimia-core 0.5.5, --scope accepts local, shared, or global. The old private scope has been replaced. local and shared secrets support per-user overrides: when a user_id is supplied, the resolver first tries the user-specific value and falls back to the scope default. global secrets have a single value. Use --user-id / -u on put and get to manage overrides.

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

As of alquimia-core 0.5.5, registering a topic creates its vector collection up front by default (ensure_collection=True). alquimia registry topics add-file reports the chunk count and tells you when the uploaded blob was deduplicated. alquimia registry topics rebuild shows each file’s name next to its registered_file_id. alquimia registry flush-version <tag> also cleans up the <tag>/... blob copies created for versioned snapshots.

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 registry explore catalog [--kind agentspace|brain]	List published artifacts from the namespace index (0.5.3+)
alquimia registry explore entry <repo>:<tag>	Show a single index entry (0.5.3+)

alquimia explore repos --registry ghcr.io/acme
alquimia explore tags ghcr.io/acme/agents/production
alquimia registry explore catalog --registry ghcr.io/acme --kind agentspace
alquimia registry explore entry ghcr.io/acme/agents/production:v1.2.0

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 exec production/support-bot:v1.2.0 "What is the refund policy?" --no-cache
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 fetch --namespace production \
  --target ghcr.io/acme/agents/staging --tag v1.0.0
alquimia registry topics rebuild product-docs --namespace production

Run a versioned agentspace without changing the workspace

# Pull an OCI tag into a cached versioned snapshot
alquimia registry fetch --namespace myspace --tag v1.2.0

# Force a fresh pull from OCI
alquimia registry fetch --namespace myspace --tag v1.2.0 --no-cache

# List cached snapshots
alquimia registry versions --namespace myspace

# Run an agent from a snapshot
alquimia local exec myspace/support-bot:v1.2.0 "What is the refund policy?"

# Remove a cached snapshot
alquimia registry flush-version --namespace myspace v1.2.0

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

Related pages

• How to create and publish an agent
• How to add a tool
• How to register a model
• How to ingest files into a topic
• Publish and pull an agentspace
• Registry & OCI concepts