assertion-cli 0.5.18

CLI for the Assertion API

Assertion CLI

CLI for the Assertion API.

Usage

The CLI targets https://app.tryassertion.com by default; set ASSERTION_BASE_URL (e.g. http://localhost:8000) to point at another backend.

Run locally from the workspace:

uv run --package assertion-cli asrt --help

Install as a uv tool from PyPI:

uv tool install assertion-cli              # latest
uv tool install --reinstall assertion-cli  # upgrade in place

The CLI package declares all of its direct runtime dependencies. At the moment that set is httpx, pydantic, and typer.

After installation:

asrt install                           # one-time onboarding: write skill files, AGENTS.md/CLAUDE.md pointer, .gitignore
asrt login                             # authenticate this repo (generate a token at Settings → Authentication)
asrt session start                     # per work session: record the diff base (current HEAD)
asrt stacks
asrt checkpoint --stack <stack-id> "Implemented X\nUpdated Y"
asrt checkpoint --continue "Implemented Y"
asrt decision --yes <checkpoint-id>   # optional, only after a failed checkpoint
asrt verify                            # submit final verification (non-blocking)
asrt verify --force                    # submit even when review diff is unchanged
asrt verify-status                     # one-shot poll; loop with your own sleep until terminal

Authentication

asrt login stores your API token in a global, user-level file — ~/.assertion/credentials.json (mode 0600) — with an inverted repo index:

{
  "version": 2,
  "tokens": { "alk_...": ["acme/mvp", "acme/docs"] },
  "repo_index": { "acme/mvp": "alk_...", "acme/docs": "alk_..." }
}

Run it from inside the repo it should authenticate. It validates the token and confirms the repo's origin remote is connected to a stack in the token's workspace before saving the token against that workspace's stack repos, so each repo can target a different workspace while moved folders and fresh clones keep working. asrt logout removes the current repo's saved auth; asrt whoami shows which token is in effect.

Token resolution at call time, in order:

1. the token in repo_index for the current repo's GitHub owner/repo;
2. a legacy entry for the current repo path in ~/.assertion/credentials.json;
3. the ASSERTION_API_TOKEN environment variable (a backup for CI, or repos with no remote that asrt login won't store);

with a clear "run asrt login" error when neither is present. The API base URL defaults to https://app.tryassertion.com; override it with ASSERTION_BASE_URL for a local backend.

Publishing a new version

1. Bump the version in cli/pyproject.toml.
2. Commit and push to main.

That's it. The Publish CLI to PyPI workflow auto-triggers on pushes that change cli/pyproject.toml. It reads the version from the file, runs tests, builds, publishes to PyPI, and pushes a cli-v<version> tag.

If the version hasn't changed (e.g. you updated a dependency), the workflow skips publishing — only version bumps trigger a publish.

You can also trigger the workflow manually from the GitHub Actions UI — it reads the version from the current pyproject.toml on main.

Prerequisite: PYPI_TOKEN must be set as a GitHub Actions secret — a PyPI API token with upload scope for assertion-cli.