Installation¶

Prerequisites¶

Python 3.10+ — check with python3 --version
uv (recommended) or pipx — for isolated tool installation

Install from GCP Artifact Registry¶

The recommended way to install grace-cli is as an isolated tool via uv:

uv tool install grace-cli \
  --index https://us-central1-python.pkg.dev/PROJECT/python-packages/simple/

Or with pipx (1.4+):

pipx install grace-cli \
  --extra-index-url https://us-central1-python.pkg.dev/PROJECT/python-packages/simple/

GCP authentication

If the Artifact Registry requires authentication, make sure you have Application Default Credentials configured:

gcloud auth application-default login

Install for local development¶

If you're developing grace-cli itself, clone the monorepo and install in editable mode:

cd cyber-grace/grace-cli
SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0.dev0 uv sync --dev

This installs grace-cli along with grace-api-py (as an editable path dependency) and all development tools (pytest, ruff, mkdocs).

Version bootstrapping

The SETUPTOOLS_SCM_PRETEND_VERSION variable is only needed until the first grace-cli/v* git tag exists. After that, hatch-vcs derives the version automatically from tags.

uv run in local dev

With uv sync, the grace command lives inside the project virtual environment. Prefix all commands with uv run:

uv run grace --version
uv run grace auth login --env dev

The bare grace command is only available when installed globally via uv tool install or pipx install. The rest of this documentation uses the bare grace form for brevity — prepend uv run when developing locally.

Optional extras¶

GCS file transfer¶

The grace data transfer --copy-files feature requires the google-cloud-storage SDK. Install it with the gcs extra:

uv tool install 'grace-cli[gcs]' \
  --index https://us-central1-python.pkg.dev/PROJECT/python-packages/simple/

Or in local development:

cd cyber-grace/grace-cli
SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0.dev0 uv sync --dev --extra gcs

You also need Application Default Credentials for GCS access:

gcloud auth application-default login

Shell completion¶

Typer supports auto-completion for bash, zsh, and fish. Install it once:

bashzshfish

grace --install-completion bash
source ~/.bashrc

grace --install-completion zsh
source ~/.zshrc

grace --install-completion fish

Note

For local development, use uv run grace --install-completion bash instead.

Verify¶

grace --version
# grace-cli 0.1.0

# Or in local development:
uv run grace --version

If you see the version number, you're all set. Head to the Quickstart next.