aethis-cli 0.22.0

CLI for the Aethis developer API — author, test, and publish rulesets

aethis-cli

CLI for the Aethis developer API — evaluate eligibility, author rulesets, and publish from the terminal.

Install

# Recommended — isolated, no venv juggling:
uv tool install aethis-cli

# Or, with pipx:
pipx install aethis-cli

Already installed? aethis update upgrades to the latest release in place (it detects how the CLI was installed and runs the matching upgrade command).

Quick start

Authoring is in private beta. Decision tools (decide, fields, explain) are public — no key required. Authoring tools (rule generation, test refinement, publishing) require an invite. Request access at aethis.ai/developer-access.

No sign-up needed. Decision tools work immediately.

# Browse the public showcase catalogue — no API key required
aethis rulesets list

# Inspect the input fields a ruleset expects
aethis fields -b <slug-or-ruleset_id>

# Get human-readable rule descriptions
aethis explain -b <slug-or-ruleset_id>

# Evaluate eligibility against a published ruleset
aethis decide -b <slug-or-ruleset_id> -i '{"some.field": 35, "other.field": true}'

Authentication

Decision tools (decide, fields, explain) call public endpoints and never need a key. Authoring tools (generate, publish, projects list, etc.) need an API key — and the CLI manages that for you.

Authoring is in private beta — aethis login will only complete for invited developers. Request access at aethis.ai/developer-access.

There are three ways the key can arrive:

1. Explicit sign-in (the canonical first-time setup):

aethis login

Opens your browser, completes Clerk OAuth, mints a fresh ak_live_... key, and stores it at ~/.config/aethis/credentials. One-time per machine.

2. Lazy auth (the default — since v0.6.0):

If you skip step 1 and run an authenticated command directly, you'll get an inline prompt:

$ aethis init
No API key found. Open browser to sign in? [Y/n]

Hit enter, the browser flow runs, the command resumes. Same effect as aethis login followed by your original command, in one step.

3. CI / scripts — --no-prompt:

For any non-interactive context (stdin not a TTY, CI runners, piped commands) the CLI auto-skips the prompt and exits with a clear AuthRequired error. To force this behaviour even on a TTY:

aethis --no-prompt projects list

Pass --api-key <ak_live_...> to bypass the cache entirely (useful when you want to test a key without committing to it).

Manage existing keys with aethis account keys (list, masked) and aethis account revoke <key_id> (revoke). aethis account generate mints an additional key — for rotation, multi-machine setups, or scoped access. For first-time setup just use aethis login.

Author your own rules (private beta)

Rule authoring is invite-only private beta. Decision tools (aethis decide, aethis fields, aethis explain) work immediately with no sign-up — this section is for approved beta tenants. Request access →

The authoring workflow follows a four-stage loop: discover, synthesise, test, publish. A ruleset cannot be published with failing tests.

# 1. Initialise a project (no-arg form prompts for a name; auto-runs `aethis login` if needed)
aethis init

# 2. Add source documents and guidance
#    (put PDFs/text in .aethis/sources/, hints in .aethis/guidance/hints.yaml)

# 3. Generate a rule ruleset
aethis generate

# 4. Run test cases
aethis test

# 5. Publish the ruleset
aethis publish

aethis init runs as a wizard: prompts for a project name (default = current directory), runs sign-in if you're not authed yet, scaffolds .aethis/, and prints the next-step ladder. Pass --no-prompt for scripted use (it'll fail fast on missing values rather than prompt).

Try the example

A complete, runnable example is included in examples/spacecraft-crew-rules/:

cp -r examples/spacecraft-crew-rules my-first-rules && cd my-first-rules
aethis login
aethis generate --poll
aethis test
aethis decide -i '{"space.crew.species": "Human", "space.crew.age": 35, "space.crew.flight_hours": 600, "space.crew.has_pilot_license": true, "space.crew.has_gaa_exam": true, "space.medical.cert_valid": true, "space.mission.type": "suborbital", "space.crew.has_towel": true}'

See examples/spacecraft-crew-rules/README.md for details.

Commands

Decision (no API key required)

Command	Description
aethis rulesets list	Browse the public showcase catalogue (auto-falls through when no project context)
aethis rulesets list --public	Same, explicit form
aethis decide -b <slug-or-ruleset_id> -i '<json>'	Evaluate eligibility. Add --explain for trace output.
aethis fields -b <slug-or-ruleset_id>	Show input fields the ruleset expects
aethis explain -b <slug-or-ruleset_id>	Human-readable rule descriptions

Authoring

Command	Description
aethis init	Initialise a new project in the current directory
aethis generate [--poll]	Upload sources + guidance, trigger generation
aethis status	Check generation job progress
aethis test	Run test cases against the latest ruleset
aethis publish [--force]	Set the latest ruleset as active

Guidance (project-level)

Project guidance lives in .aethis/guidance/hints.yaml and is uploaded by aethis generate. These commands manage hints server-side after upload.

Command	Description
aethis guidance list	List active hints for the current project
aethis guidance export <file>	Export the current project's hints to YAML
aethis guidance import <file>	Import hints from a YAML file
aethis guidance deactivate <hint_id>	Deactivate a specific hint

Projects & rulesets

Command	Description
aethis projects list	List your projects
aethis projects show <project_id>	Show project details
aethis projects archive <project_id>	Archive a project
aethis rulesets list	List published rulesets
aethis rulesets archive <ruleset_id>	Archive a ruleset

Rulebooks (the converged 2-term model, login required for authoring)

A Rulebook is the whole form — the unit /decide evaluates against. It owns a locked field vocabulary, an outcome_logic composition expression, rulebook-level test cases, and an integer version history. Rulesets are named, versioned members of a Rulebook.

Command	Description
aethis rulebooks list	List your tenant's rulebooks (or, with no key, the public catalogue)
aethis rulebooks show <id-or-slug>	Full configuration including outcome_logic
aethis rulebooks create <name> --domain <d> [--slug ...]	Create a draft rulebook
aethis rulebooks set-fields <id> -f fields.yaml	Replace the locked field vocabulary
aethis rulebooks lock-fields <id> / unlock-fields <id> / get-fields <id>	Manage the field-lock state
aethis rulebooks set-logic <id> -f logic.yaml	Set the composition expression (Expr AST)
aethis rulebooks decide <id-or-slug> -i '<json>'	Evaluate the composed rulebook (requires API key)
aethis rulebooks activate <id> / archive <id>	Lifecycle
aethis rulesets create <rulebook> <ruleset_name>	Create a draft ruleset inside a rulebook
aethis rulesets list <rulebook>	List rulesets in a rulebook
aethis rulesets show <rulebook> <ruleset_name>	Full version history for one ruleset name
aethis rulesets promote-to-live <rulebook> <ruleset_name> <ruleset_id>	Atomic promotion: demote prior live → archived, promote candidate, cut new Rulebook version

Account

Command	Description
aethis login	Sign in and store an API key locally (first-time setup)
aethis login --profile <name>	Sign in into a named profile slot (keeps default untouched)
aethis account generate	Mint an additional API key (rotation, multi-machine, scoped access)
aethis account keys	List your API keys (masked)
aethis account revoke <key_id>	Revoke a key
aethis update [--check]	Update the CLI to the latest release (--check only reports)

Profiles

Multiple credential profiles let you keep separate personas — say, an admin key plus a "fresh signup" perspective — and switch between them without re-authenticating. The reserved profile name anonymous forces unsigned mode (no X-API-Key header sent), so you can verify exactly what an unauthenticated user would see.

# Create profiles (or use `aethis login --profile <name>` for OAuth)
aethis profile add admin --api-key ak_live_…
aethis profile add new-dev --api-key ak_test_…

# See them, with `*` next to the active one
aethis profile list

# Switch the sticky default
aethis profile use new-dev

# One-off override (doesn't change the sticky default)
aethis --profile admin rulesets list
aethis --profile anonymous rulesets list   # forces public-mode

# Delete one
aethis profile remove new-dev

Profile selection order: --profile flag > AETHIS_PROFILE env > the sticky active_profile field in ~/.config/aethis/credentials > default. The AETHIS_API_KEY env var still takes precedence over all profile machinery — set it to short-circuit the cache for one invocation.

Command	Description
aethis profile list	Show all profiles + which one is active
aethis profile use <name>	Set the sticky default profile
aethis profile add <name> [--api-key …]	Create or update a named profile
aethis profile remove <name>	Delete a profile

MCP one-liner

Wire up the Aethis MCP server in your AI editor without hand-editing JSON. Picks up the API key cached by aethis login, drops a canonical aethis server entry into the right config file, and preserves any other MCP servers you already have.

Onboarding an AI coding agent end-to-end? See docs.aethis.ai/agents/onboarding — install + verify + auth + workflow patterns in one page.

# One editor at a time
aethis mcp install --target cursor
aethis mcp install --target claude-code      # writes ./.mcp.json (project-local)
aethis mcp install --target claude-desktop
aethis mcp install --target windsurf

# Or all four at once
aethis mcp install --target all

# Reverse it (only removes the `aethis` entry, leaves others alone)
aethis mcp uninstall --target cursor

The command is idempotent — re-run it after aethis login rotates your key and the entry updates in place. Restart your editor to pick up the change.

Target	Config path
claude-code	<cwd>/.mcp.json (project-scoped)
cursor	~/.cursor/mcp.json
claude-desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Linux: ~/.config/Claude/claude_desktop_config.json
windsurf	~/.codeium/windsurf/mcp_config.json

Project structure

After aethis init, your project looks like:

my-rules/
  .aethis/
    aethis.yaml          # project config
    state.json           # tracked IDs (project, ruleset, job)
    sources/             # PDF/text source documents
    guidance/
      hints.yaml         # guidance hints for the code synthesizer
    tests/
      scenarios.yaml     # golden test cases

aethis.yaml

project: my-rules
api_key_env: AETHIS_API_KEY

scenarios.yaml

tests:
  - name: "Eligible — all requirements met"
    inputs:
      space.crew.age: 35
      space.crew.flight_hours: 600
      space.crew.has_pilot_license: true
    expect:
      outcome: eligible
  - name: "Not eligible — no medical cert"
    inputs:
      space.medical.cert_valid: false
    expect:
      outcome: not_eligible

Environment variables

Variable	Description	Required	Default
AETHIS_API_KEY	Your API key (ak_live_...). Bypasses the cached credential and any profile machinery.	Authoring only	—
AETHIS_PROFILE	Select a named credential profile (overrides the sticky default; see aethis profile).	No	default
AETHIS_BASE_URL	Override the API host (staff/dev use; staging or self-hosted).	No	https://api.aethis.ai
ANTHROPIC_API_KEY	Forwarded per-request to the generation endpoint when running aethis generate. Never stored server-side.	Authoring only	—

Extending with plugins

aethis-cli discovers third-party plugins via Python entry points under the aethis_cli.plugins group. A plugin is any installed package that exposes a register(app: typer.Typer) -> None callable; at startup the CLI calls it with the root Typer app and the plugin attaches extra commands.

Example pyproject.toml:

[project.entry-points."aethis_cli.plugins"]
my_plugin = "my_package.plugin:register"

Example my_package/plugin.py:

import typer

def register(app: typer.Typer) -> None:
    @app.command()
    def hello() -> None:
        typer.echo("hello from my plugin")

Staff-only tools (DSL source viewer, IAM registry, domain-guidance management, --base-url override) live in the private aethis-cli-internal package, installed on request.

Development

git clone https://github.com/aethis-ai/aethis-cli.git
cd aethis-cli
uv pip install -e ".[dev]"
pytest tests/ -v

Shell completions

# Install tab completion for your shell
aethis --install-completion bash   # or zsh, fish, powershell

Troubleshooting

aethis generate times out but server continues The server finishes even if your client disconnects. Wait 10–15 min, then run aethis rulesets list — if the ruleset appeared, run aethis test and aethis publish. Do not re-trigger generation; that creates a duplicate run.

aethis publish fails with "tests are failing" publish refuses a ruleset with failing tests. Fix with guidance + regenerate, or pass --force (not recommended for production).

422 Validation error on aethis decide DATE fields must be passed as integer ordinals, not ISO strings. 2025-04-13 → 739354:

python3 -c "from datetime import date; print(date(2025,4,13).toordinal())"

Auth error: … Your API key is missing, expired, or revoked. Run aethis login to mint a new one. (As of v0.6.0 the CLI prompts for sign-in inline when an authenticated command runs without a key; use --no-prompt to suppress that in CI.)

403 Forbidden: missing scope Your key lacks the required scope for the command. aethis whoami shows what your current key can do. Contact support to upgrade scopes.

Benchmarks

See how the engine compares to frontier LLMs on real-world eligibility rules: aethis-examples

License

MIT