Skip to content

Installing spot-cli

spot-cli ships as a Docker image alongside the rest of the platform. A small POSIX wrapper invokes the image so you can call spot-cli ... from anywhere instead of typing docker compose --profile cli run --rm cli ....

Pick the path that matches how you installed SPOT.

This is the path for operators using the SPOT_Project/deploy repository (the supported install method).

The CLI is an optional component — like the bundled Ollama side-car or the SMTP retriever — and is enabled the same way: by adding cli to COMPOSE_PROFILES in your .env. The deploy stack ships:

  • a cli service in docker-compose.yml, gated on profiles: [cli], pinned to ${CORE_REGISTRY}/spot-cli:${CORE_VERSION};
  • a scripts/spot-cli wrapper that runs the image transparently, so you can type spot-cli auth login instead of the full docker compose run --rm cli auth login.

Install

cd /opt/spot                        # or wherever you cloned deploy

# 1. Enable the cli profile. If COMPOSE_PROFILES is already set
#    (e.g. for ollama), append `cli` with a comma — don't replace it.
echo 'COMPOSE_PROFILES=cli' >> .env

# 2. Pull the image. With the profile active, compose now sees the
#    cli service; without the profile this fails with
#    `no such service: cli`.
docker compose pull cli

# 3. Symlink the wrapper onto PATH (symlink keeps it in sync with
#    `git pull`; `install -m 0755 ...` is the standalone alternative).
sudo ln -s "$PWD/scripts/spot-cli" /usr/local/bin/spot-cli

Without sudo:

mkdir -p "$HOME/.local/bin"
ln -s "$PWD/scripts/spot-cli" "$HOME/.local/bin/spot-cli"

Verify

which spot-cli
spot-cli --help
spot-cli auth login

The wrapper forwards SPOT_API_URL (default http://api-gateway:8000) and persists auth tokens on the host under ~/.config/spot-cli/ so they survive across --rm invocations. If the image is missing locally the wrapper exits with a clear pointer back at step 2 above — it never runs docker pull directly, on purpose: keeping image pulls inside compose preserves the version pin and the COMPOSE_PROFILES gate.

Upgrade

# Bump CORE_VERSION in .env (or accept the deploy default), then:
docker compose pull cli              # picks up the new tag

Old images can be reclaimed with docker image prune later.

Using raw docker compose run (no wrapper)

If you don't want the wrapper on PATH at all, the same profile unlocks the direct compose form:

docker compose run --rm cli auth login
docker compose run --rm cli health

Same image, same auth-token volume — the wrapper is only there to save typing.

On a development install (core repo)

For SPOT contributors working out of the SPOT_Project/core repository directly.

The wrapper lives at services/cli/spot-cli and is already executable. Drop it on your PATH once -- a symlink keeps it in sync with repo updates, a copy makes the install standalone:

# Option A: symlink (recommended; tracks repo updates)
sudo ln -s "$PWD/services/cli/spot-cli" /usr/local/bin/spot-cli

# Option B: copy (standalone; survives moving the repo)
sudo install -m 0755 services/cli/spot-cli /usr/local/bin/spot-cli

Without sudo, install under a user-owned directory that your shell already has on PATH:

mkdir -p "$HOME/.local/bin"
ln -s "$PWD/services/cli/spot-cli" "$HOME/.local/bin/spot-cli"

If ~/.local/bin is not yet on PATH (echo $PATH to check), add it to your shell rc:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc

Build the image once -- the first invocation triggers a docker compose build automatically, but you can pre-build to avoid the wait:

make docker:build SERVICE=cli

Tab completion

Sourcing the included static completion stops the shell from spawning the Docker container on every <Tab>. The completion file uses bash-style syntax that works in both bash and zsh.

Bash:

# deploy install
echo 'source /opt/spot/scripts/spot-cli-completion.bash' >> ~/.bashrc

# development install
echo 'source /path/to/services/cli/spot-cli-completion.bash' >> ~/.bashrc

# system-wide
sudo cp <wrapper-dir>/spot-cli-completion.bash /etc/bash_completion.d/spot-cli

Zsh (load bashcompinit first so complete -F is recognised):

# Once, in ~/.zshrc:
autoload -U +X bashcompinit && bashcompinit
autoload -U +X compinit     && compinit
source /opt/spot/scripts/spot-cli-completion.bash

The completion is intentionally static (it knows the command groups, not their options) so <Tab> costs zero processes.

Running against a remote deployment

The wrapper attaches to the platform's docker network (auto-resolved from compose labels, e.g. spot_spot-network) and forwards SPOT_API_URL. Override either when needed:

SPOT_CLI_NETWORK=other_spot-network spot-cli health
SPOT_API_URL=https://spot.example.com spot-cli auth login

Other knobs the wrapper honours: SPOT_CLI_IMAGE (defaults to the deploy registry image or spot-cli:latest for the dev install) and SPOT_TOKEN_DIR_HOST (default ~/.config/spot-cli).

For a deployment exposed over the network rather than via local compose, override the api-gateway URL directly:

SPOT_API_URL=https://spot.example.com spot-cli auth login

Benchmark directories

spot-cli benchmark reads raw datasets from SPOT_DATASETS_DIR and writes normalized files plus run outputs to SPOT_BENCHMARK_DIR. The wrapper bind-mounts the host paths into the container when these are set:

export SPOT_DATASETS_DIR=/home/me/spot/datasets
export SPOT_BENCHMARK_DIR=/home/me/spot/benchmarks

spot-cli benchmark normalize --all
spot-cli benchmark run --workflow default-workflow --all

SPOT_DATASETS_DIR is mounted read-only (raw corpora are never mutated). SPOT_BENCHMARK_DIR is read-write and is created on the host if it does not already exist.

Next steps