CLI Reference

v2 (legacy). This page describes the v2 application (the RAG chatbot) on the main branch. It is not the 3.0 documentation. v2 keeps running on main until the cutover; see Moving from v2 to 3.0.

The Archi CLI provides commands to create, manage, and monitor deployments.

Installation

The CLI is installed automatically with pip install -e . from the repository root. Verify with:

which archi

Commands

archi create

Create a new Archi deployment.

archi create --name <name> --config <config.yaml> --env-file <secrets.env> --services <services> [OPTIONS]

Required options:

Option Description
--name, -n Name of the deployment
--config, -c Path to YAML configuration file (repeatable for multiple files)

Recommended options:

Option Description
--env-file, -e Path to the secrets .env file
--services, -s Comma-separated list of services to enable (e.g., chatbot,uploader)

Optional flags:

Option Description Default
--config-dir, -cd Directory containing configuration files —
--podman, -p Use Podman instead of Docker Docker
--gpu-ids GPU configuration: all or comma-separated IDs (e.g., 0,1) None
--tag, -t Image tag for built containers 2000
--hostmode Use host network mode for all services Off
--verbosity, -v Logging verbosity level (0=quiet, 4=debug) 3
--force, -f Overwrite existing deployment if it exists Off
--dry, --dry-run Validate and show what would be created without deploying Off

Examples:

# Basic deployment with Ollama
archi create -n my-archi -c config.yaml -e .secrets.env \
  --services chatbot --podman

# Full deployment with GPU and multiple services
archi create -n prod-archi -c config.yaml -e .secrets.env \
  --services chatbot,uploader,grafana \
  --gpu-ids all

# Dry run to validate configuration
archi create -n test -c config.yaml -e .secrets.env \
  --services chatbot --dry-run

Notes:

  • The CLI checks that host ports are free before deploying. If a port is in use, adjust services.*.external_port in your config.
  • The first deployment builds container images from scratch (may take several minutes). Subsequent deployments reuse images.
  • Use -v 4 for debug-level logging when troubleshooting.

archi delete

Delete an existing deployment.

archi delete --name <name> [OPTIONS]
Option Description
--name, -n Name of the deployment to delete
--rmi Also remove container images
--rmv Also remove volumes
--keep-files Keep deployment files on disk
--list List all deployments

Examples:

# Delete deployment and clean up everything
archi delete -n my-archi --rmi --rmv

# Delete but keep data volumes
archi delete -n my-archi --rmi

archi restart

Restart a specific service in an existing deployment without restarting the entire stack.

archi restart --name <name> --service <service> [OPTIONS]
Option Description Default
--name, -n Name of the existing deployment Required
--service, -s Service to restart chatbot
--config, -c Updated configuration file(s) —
--config-dir, -cd Directory containing configuration files —
--env-file, -e Updated secrets file —
--no-build Restart without rebuilding the container image Off
--with-deps Also restart dependent services Off
--podman, -p Use Podman instead of Docker Docker
--verbosity, -v Logging verbosity (0-4) 3

Examples:

# Quick config update (no rebuild needed)
archi restart -n my-archi --service chatbot --no-build

# Rebuild after code changes
archi restart -n my-archi --service chatbot -c updated_config.yaml

# Re-scrape data sources
archi restart -n my-archi --service data_manager

# Restart with updated secrets
archi restart -n my-archi --service chatbot -e new_secrets.env --no-build

archi list-services

List all available services and data sources with descriptions.

archi list-services

archi list-deployments

List all existing deployments.

archi list-deployments

archi evaluate

Launch the benchmarking runtime to evaluate configurations against a set of questions and answers.

archi evaluate --name <name> --env-file <secrets.env> --config <config.yaml> [OPTIONS]

Supports the same flags as create (--podman, --gpu-ids, --tag, --hostmode, --verbosity, --force). Configuration files should define the services.benchmarking section.

Example:

archi evaluate -n benchmark \
  -c examples/benchmarking/benchmark_configs/example_conf.yaml \
  -e .secrets.env --gpu-ids all

See Benchmarking for full details on query format and evaluation modes.


archi install

Create and optionally install a Helm chart for an Archi deployment.

archi install --name <name> --config <config.yaml> --templates-dir <dir> --env-file <secrets.env> --services <services> [OPTIONS]

Supports --gpu-ids with the same values as create. For explicit IDs such as 0,1, the generated chart sets NVIDIA_VISIBLE_DEVICES and requests the matching nvidia.com/gpu count. For all, the chart sets NVIDIA_VISIBLE_DEVICES=all; adjust gpu.count in values.yaml if your Kubernetes cluster requires an explicit GPU limit.


Environment Variables

Variable Description
ARCHI_DIR Override the deployment directory (default: ~/.archi)
OLLAMA_HOST Ollama server address (default: http://localhost:11434)

Troubleshooting

Port Conflicts

If a port is already in use, the CLI will report an error. Adjust services.*.external_port in your config:

services:
  chat_app:
    external_port: 7862  # default: 7861
  grafana:
    external_port: 3001  # default: 3000

GPU Issues

GPU access requires NVIDIA drivers and the NVIDIA Container Toolkit.

Podman:

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
nvidia-ctk cdi list

Docker:

sudo nvidia-ctk runtime configure --runtime=docker

Verbose Logging

Add -v 4 to any command for debug-level output:

archi create [...] -v 4

Multiple Deployments

Multiple deployments can run on the same machine. Container networks are separate, but be careful with external port assignments. See Advanced Setup.