Merge pull request #12 from mozilla-ai/add-cli

Add Comprehensive Management CLI with Rich Formatting

Author: tbille

.gitignore

@@ -13,3 +13,6 @@ wheels/
 
 # Generated by setuptools_scm; do not commit
 src/any_llm_platform_client/_version.py
+
+.coverage
+.ralph/

AGENTS.md

@@ -0,0 +1,158 @@
+# AGENTS.md - Agent Development Guide
+
+This document is the **table of contents** for AI coding agents working in this repository. It provides a map to deeper documentation rather than exhaustive instructions.
+
+## Quick Start
+
+```bash
+# Setup
+uv sync --dev && uv run pre-commit install
+
+# Run tests
+uv run pytest -v
+
+# Run single test
+uv run pytest tests/test_cli.py::test_cli_help -v
+
+# Lint and format
+uv run ruff check . --fix && uv run ruff format .
+```
+
+## Project Identity
+
+- **Package**: `any-llm-platform-client`
+- **CLI**: `any-llm`
+- **Python**: 3.11+ (compatible with 3.11–3.14)
+- **Package Manager**: `uv` (or `pip`)
+- **Source**: `src/any_llm_platform_client/`
+- **Tests**: `tests/`
+
+## Repository Knowledge Map
+
+The repository follows a **structured documentation approach** inspired by agent-first development principles. Knowledge lives in versioned, discoverable artifacts—not external documents or chat threads.
+
+### Core Documentation
+
+| Document | Purpose |
+|----------|---------|
+| `docs/DEVELOPMENT.md` | Development workflow, commands, testing |
+| `docs/CODE_STYLE.md` | Style guide, formatting, naming, type hints |
+| `docs/CLI_USAGE.md` | CLI commands, authentication, examples |
+| `docs/architecture/CRYPTOGRAPHY.md` | Encryption design, security properties |
+| `docs/architecture/PROJECT_STRUCTURE.md` | Code organization, module responsibilities |
+
+### Quick Reference
+
+- **Build/Test/Lint**: See `docs/DEVELOPMENT.md`
+- **Code Style**: See `docs/CODE_STYLE.md`
+- **CLI Usage**: See `docs/CLI_USAGE.md`
+- **Architecture**: See `docs/architecture/`
+
+## Core Principles
+
+Following the OpenAI agent-first development model, this repository enforces:
+
+1. **Agent Legibility**: Code structure optimized for agent reasoning
+2. **Repository as Truth**: All knowledge versioned in-repo (not in Slack/Docs)
+3. **Progressive Disclosure**: Start with this map, navigate to details as needed
+4. **Mechanical Enforcement**: Linters enforce architecture, not docs alone
+
+## Code Style Highlights
+
+```python
+# Type hints (required)
+def decrypt_data(encrypted_data: bytes, private_key: nacl.public.PrivateKey) -> bytes:
+    """Decrypt data using X25519 sealed box.
+
+    Args:
+        encrypted_data: The encrypted data bytes
+        private_key: The X25519 private key for decryption
+
+    Returns:
+        Decrypted data as bytes
+
+    Raises:
+        ValueError: If decryption fails
+    """
+    ...
+
+# Modern syntax
+items: list[str] = []  # Not List[str]
+result: str | None = None  # Not Optional[str]
+
+# Imports (grouped: stdlib → third-party → local)
+import logging
+from typing import Any
+
+import httpx
+from rich.console import Console
+
+from .client import AnyLLMPlatformClient
+```
+
+**Key Rules**:
+- 120 char line length
+- Double quotes for strings
+- Google docstring format
+- Type hints required (except tests, `__init__.py`)
+- No bare `except:`, use specific exception types
+
+## Project Structure
+
+```
+src/any_llm_platform_client/
+├── __init__.py           # Public API exports
+├── cli.py                # Click CLI commands
+├── client.py             # Core decryption client
+├── client_management.py  # Management API (CRUD)
+├── crypto.py             # X25519 cryptography
+└── exceptions.py         # Custom exceptions
+
+tests/
+├── test_basic.py         # Basic imports
+├── test_cli.py           # CLI commands
+├── test_cli_integration.py  # Integration tests
+└── test_client.py        # Client library tests
+
+docs/
+├── DEVELOPMENT.md        # Build, test, lint
+├── CODE_STYLE.md         # Style guide
+├── CLI_USAGE.md          # CLI reference
+└── architecture/         # Design docs
+    ├── CRYPTOGRAPHY.md
+    └── PROJECT_STRUCTURE.md
+```
+
+## Environment Variables
+
+- `ANY_LLM_USERNAME`: Username for management commands
+- `ANY_LLM_PASSWORD`: Password for management commands
+- `ANY_LLM_PLATFORM_URL`: API base URL (default: `http://localhost:8000/api/v1`)
+- `ANY_LLM_KEY`: Encryption key format: `ANY.v1.<kid>.<fingerprint>-<base64_key>`
+
+## Common Pitfalls
+
+1. **Don't** skip type annotations in production code
+2. **Don't** use mutable default arguments
+3. **Don't** commit secrets (pre-commit hooks check)
+4. **Don't** ignore ruff's bugbear rules (B)—they catch real bugs
+5. **Don't** create files without reading existing ones first
+
+## CI/CD
+
+- **Platforms**: Linux, macOS, Windows
+- **Python versions**: 3.11, 3.12, 3.13, 3.14
+- **Pre-commit**: Linting, formatting, secrets detection
+- **Coverage**: Codecov (Ubuntu + Python 3.11 only)
+
+## Where to Look Next
+
+- **First time here?** Start with `docs/DEVELOPMENT.md`
+- **Writing code?** Check `docs/CODE_STYLE.md`
+- **Using the CLI?** See `docs/CLI_USAGE.md`
+- **Understanding crypto?** Read `docs/architecture/CRYPTOGRAPHY.md`
+- **Need examples?** See `docs/CLI_USAGE.md` examples section
+
+---
+
+**Philosophy**: This file is a **map**, not a manual. For detailed instructions, follow the links above to specialized documentation.

README.md

@@ -39,15 +39,169 @@ any-llm <provider>
 
 ### Command Line Interface
 
-Interactive mode (prompts for provider):
+The CLI provides a unified interface for managing your any-llm platform:
+
+```bash
+# Get help
+any-llm --help
+
+# View available commands
+any-llm project --help
+any-llm key --help
+any-llm budget --help
+any-llm client --help
+```
+
+#### Authentication
+
+Set credentials for management commands:
+
+```bash
+export ANY_LLM_USERNAME="your-email@example.com"
+export ANY_LLM_PASSWORD="your-password"  # pragma: allowlist secret
+export ANY_LLM_PLATFORM_URL="http://localhost:8000/api/v1"  # optional
+```
+
+#### Managing Projects
+
 ```bash
+# List all projects
+any-llm project list
+
+# Create a new project
+any-llm project create "My Project" --description "My project description"
+
+# Show project details
+any-llm project show <project-id>
+
+# Update a project
+any-llm project update <project-id> --name "Updated Name"
+
+# Delete a project
+any-llm project delete <project-id>
+```
+
+#### Managing Provider Keys
+
+```bash
+# List provider keys for a project
+any-llm key list <project-id>
+
+# Create a provider key
+any-llm key create <project-id> openai <encrypted-key>
+
+# Update a provider key
+any-llm key update <provider-key-id> <encrypted-key>
+
+# Archive a provider key (soft delete)
+any-llm key delete <provider-key-id>
+
+# Permanently delete a provider key
+any-llm key delete <provider-key-id> --permanent
+
+# Restore an archived key
+any-llm key unarchive <provider-key-id>
+```
+
+#### Generating New Encryption Keys
+
+Generate a new encryption key and automatically migrate provider keys:
+
+```bash
+# Generate new key and migrate from old key
+any-llm key generate <project-id> --old-key "ANY.v1.<old-key>"
+
+# Generate new key without migration (archives all provider keys)
+any-llm key generate <project-id>
+
+# Skip confirmation prompts (for automation)
+any-llm key generate <project-id> --old-key "ANY.v1.<old-key>" --yes
+```
+
+This command will:
+1. Generate a new X25519 keypair
+2. Update the project's encryption key
+3. Migrate all provider keys from the old key to the new key (if old key provided)
+4. Display the new ANY_LLM_KEY (save it securely!)
+
+**Important:** Save the generated `ANY_LLM_KEY` in a secure location. It cannot be recovered if lost!
+
+**Migration Behavior:**
+- **With old key:** Successfully decrypted provider keys are re-encrypted with the new key. Keys that fail to decrypt are archived.
+- **Without old key:** All encrypted provider keys are archived. You'll need to re-enter them in the web interface.
+- **Local providers** (e.g., Ollama with empty keys) are skipped during migration.
+
+#### Decrypting Provider Keys
+
+Decrypt a provider API key using your ANY_LLM_KEY:
+
+```bash
+# Set your ANY_LLM_KEY
 export ANY_LLM_KEY='ANY.v1.<kid>.<fingerprint>-<base64_key>'
-any-llm
+
+# Decrypt a provider key
+any-llm key decrypt openai
+any-llm key decrypt anthropic
+
+# Or provide the key inline
+any-llm --any-llm-key 'ANY.v1...' key decrypt openai
+```
+
+#### Managing Budgets
+
+```bash
+# List budgets for a project
+any-llm budget list <project-id>
+
+# Create a project budget
+any-llm budget create <project-id> 100.00 --period monthly
+
+# Show a specific budget
+any-llm budget show <project-id> monthly
+
+# Update a budget
+any-llm budget update <project-id> monthly 200.00
+
+# Delete a budget
+any-llm budget delete <project-id> monthly
 ```
 
-Direct mode (specify provider as argument):
+Budget periods: `daily`, `weekly`, `monthly`
+
+#### Managing Clients
+
 ```bash
-any-llm openai
+# List clients for a project
+any-llm client list <project-id>
+
+# Create a new client
+any-llm client create <project-id> "My Client" --default
+
+# Show client details
+any-llm client show <project-id> <client-id>
+
+# Update a client
+any-llm client update <project-id> <client-id> --name "Updated Client"
+
+# Set as default client
+any-llm client set-default <project-id> <client-id>
+
+# Delete a client
+any-llm client delete <project-id> <client-id>
+```
+
+#### Output Formats
+
+All commands support two output formats:
+- `table` (default): Human-readable formatted output
+- `json`: Machine-readable JSON output for scripting
+
+```bash
+# Get JSON output for scripting
+any-llm --format json project list
+
+# Example: Extract project ID
+PROJECT_ID=$(any-llm --format json project create "New Project" | jq -r '.id')
 ```
 
 ### Configuring the API Base URL
@@ -64,13 +218,12 @@ client = AnyLLMPlatformClient(any_llm_platform_url="https://api.example.com/v1")
 challenge_data = client.create_challenge(public_key)
 ```
 
-Or set the environment variable before running the CLI. The CLI will use the
-first defined of `--api-base-url` or `ANY_LLM_PLATFORM_URL`.
+Or set the `ANY_LLM_PLATFORM_URL` environment variable before running the CLI:
 
 ```bash
 # Example: temporarily point CLI to a staging backend
 export ANY_LLM_PLATFORM_URL="https://staging-api.example.com/v1"
-any-llm openai
+any-llm key decrypt openai
 ```
 
 ### As a Python Library
@@ -166,7 +319,9 @@ asyncio.run(main())
 ANY.v1.<kid>.<fingerprint>-<base64_32byte_private_key>
 ```
 
-Generate your ANY_LLM_KEY from the project page in the web UI.
+You can generate a new ANY_LLM_KEY using:
+- The CLI: `any-llm key generate <project-id>`
+- The project page in the web UI
 
 ## Security Notes