astra-cli-agent 0.1.0

Astra — a terminal AI assistant that understands natural language and drives your dev tools.

Astra CLI

A terminal-based AI assistant that understands natural language and drives your developer tools — git, docker, kubernetes, code, and more — through a multi-agent LangGraph pipeline with local memory and RAG.

All 18 build phases are complete. See docs/ARCHITECTURE.md for the full design and HANDOFF.md for exactly what's done and what's left (mostly external setup — PyPI trusted publishing, a working LangSmith key, a local k8s cluster).

Install

Once published, install with:

pip install astra-cli-agent    # or: uv tool install astra-cli-agent

This installs the astra command on your PATH — the PyPI distribution name (astra-cli-agent) is different from the command you actually run.

Install (development)

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

or with plain pip:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Getting started

Astra needs at least one LLM provider before it can answer anything. The first time you run a command that needs one (astra ask, astra "<prompt>", astra chat) with none configured, it offers to walk you through setup right there — same as most terminal AI tools do on first run. You can also trigger it directly:

astra setup

This walks you through picking a provider (Groq, Anthropic, OpenAI, or a local Ollama server), pastes-and-tests your API key with one real, cheap request before saving it, and writes it to ~/.astra/.env — never logged, never committed. Run it again any time to add more providers (recommended, so FallbackRouter has something to fall back to).

astra hello     # sanity check: confirms install + config + whether a provider is set up
astra version   # print installed version
astra ask "..."  # one-shot LLM call, no agent pipeline
astra "explain this code"   # full natural-language agent pipeline
astra chat       # interactive REPL with streaming, history, autocomplete

Configuration

Astra reads, in order (each layer overrides the previous):

1. packaged defaults (src/astra/config/defaults.yaml)
2. ~/.astra/config.yaml (user overrides)
3. environment variables, e.g. ASTRA_APP__LOG_LEVEL=DEBUG

Provider API keys live in ~/.astra/.env (written by astra setup) or a project-local .env (copy .env.example to get started by hand instead of the wizard).

Releasing (maintainers)

CI (.github/workflows/ci.yml) runs ruff/mypy/pytest on every push and PR to main.

Publishing to PyPI (.github/workflows/release.yml) uses PyPI's trusted-publishing (OIDC) flow — no token stored in this repo. One-time setup required on PyPI, done once by whoever owns the astra-cli-agent project there:

1. Register the astra-cli-agent project on PyPI (or claim it if unclaimed).
2. In that project's PyPI settings → Publishing, add a trusted publisher: this GitHub repo, workflow file release.yml, environment name pypi.
3. In this repo's GitHub settings → Environments, create an environment named pypi (ideally with a required-reviewer rule, so a published Release doesn't auto-publish without a human glance).
4. Cut a GitHub Release (tag + "Publish release" in the UI) — that triggers the workflow.

Development

pytest
ruff check .
mypy src