alice-cli 0.1.5

ALiCE — AI research uility for the Johns Hopkins Libraries

alice-cli

Python CLI for the ALICE (Artificial Language Intelligence and Cognitive Exploration) project at Johns Hopkins. A unified tool for Bedrock credential management, model invocation, secrets operations, and AWS passthrough.

Built with Click, boto3, and Rich. Packaged with Poetry. Runs with uv/uvx.

Prerequisites

• Python 3.12+
• AWS CLI configured with an SSO profile (e.g. drcc-ai)
• Active SSO session: aws sso login --profile <PROFILE>

Installation

cd alice-cli

# Poetry (standard)
poetry install

# uv
uv pip install .

# pipx (isolated environment, recommended for CLI tools)
pipx install .

# With TUI support
poetry install --extras tui
# or with pipx
pipx install ".[tui]"

After installation, the alice command is available on your PATH.

For one-off usage without installing:

uvx --from ./alice-cli alice get-key --profile myprofile

Getting started

1. Authenticate

Run alice auth with your AWS SSO profile to validate your identity and store your Bedrock API key credentials locally:

alice auth --profile <PROFILE>

This detects your JHED from the SSO session, fetches your Bedrock API key from Secrets Manager, and saves everything (including your per-user inference profile ARNs) to ~/.alice/credentials.json.

After this initial auth, most commands work without --profile because the stored credentials are used automatically.

2. Verify your setup

alice status

Shows your SSO session state, identity, region, and namespace.

3. Get your Bedrock API key

# Print export statements (default)
alice get-key

# Load credentials into your current shell
eval $(alice get-key --eval)

# .env file format
alice get-key --env-file

# Raw JSON from Secrets Manager
alice get-key --json

Output goes to stdout. Banners and status messages go to stderr, so piping and eval work correctly.

The credential set includes: AWS_BEARER_TOKEN_BEDROCK, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, BEDROCK_ACCESS_KEY, BEDROCK_SECRET_KEY, AWS_REGION, CLAUDE_CODE_USE_BEDROCK, ANTHROPIC_MODEL, and the ANTHROPIC_DEFAULT_*_MODEL inference profile vars.

Using with Claude Code

alice auth --profile <PROFILE> --claude

This retrieves your credentials, sets all required environment variables (including your per-user application inference profile ARNs for Opus, Sonnet, and Haiku), and execs into claude. Requires claude on your PATH.

Once you've authenticated with --profile at least once, you can launch Claude using just your stored API key:

alice auth --claude

API key mode

If you have a Bedrock API key but no AWS SSO profile, you can use it directly:

alice auth --api-key <SECRET_KEY>

Or set the environment variables:

export BEDROCK_ACCESS_KEY="BedrockAPIKey-yourjhed-at-123456789012"
export BEDROCK_SECRET_KEY="ABSK..."

API key mode skips SSO and Secrets Manager entirely. Note that inference profile ARNs require at least one prior alice auth --profile <PROFILE> run to be stored — the API key alone cannot fetch them from Secrets Manager.

Invoking models

alice invoke "Explain the Krebs cycle"

# Specify a model by alias
alice invoke --model-id claude-opus-4.6 "Hello"

# Or by full model ID
alice invoke --model-id us.anthropic.claude-sonnet-4-6 "Hello"

Default model: sonnet → us.anthropic.claude-sonnet-4-6.

Model aliases

alice list-aliases

Shows all available short names (e.g. sonnet, opus, haiku, nova-pro, deepseek-r1) and their corresponding Bedrock model IDs.

List foundation models

alice list-models

Lists all available foundation models from the Bedrock API.

Secrets operations

# Get your own Bedrock API key secret
alice get-secret

# Get a secret by short name (auto-prefixes namespace/environment)
alice get-secret myapp-config

# List all secrets under the namespace/environment prefix
alice list-secrets

AWS CLI passthrough

alice run s3 ls

Forwards arguments to aws and injects --region and --profile from the alice context if not already present.

Configuration

# Show resolved config values and their sources
alice config

Defaults can be overridden with CLI flags, environment variables, or stored credentials. Precedence: CLI flag > environment variable > stored credentials > default.

Setting	Default	Env var	CLI flag
Profile	—	AWS_PROFILE	--profile
Region	us-east-1	—	--region
Namespace	drcc	ALICE_NAMESPACE	--namespace
Environment	ai	ALICE_ENVIRONMENT	--environment
API key	—	BEDROCK_SECRET_KEY	--api-key

Command reference

Command	Description
alice auth	Authenticate and store credentials
alice auth --claude	Authenticate and launch Claude Code
alice get-key	Print Bedrock credentials for shell export
alice get-secret [name]	Retrieve a secret (defaults to your own)
alice list-secrets	List secrets under your namespace
alice invoke <prompt>	Invoke a Bedrock model
alice list-aliases	Show model alias → model ID mappings
alice list-models	List available Bedrock foundation models
alice run <args>	AWS CLI passthrough
alice config	Show resolved configuration
alice status	Health check (SSO, identity, region)

Global options

Option	Default	Description
--profile	$AWS_PROFILE	AWS CLI profile
--region	us-east-1	AWS region
--namespace	drcc	Resource namespace
--environment	ai	Deployment environment
--api-key	$BEDROCK_SECRET_KEY	Bedrock API key (skips SSO)
--quiet	off	Suppress banner and status messages
--tui	off	Launch interactive TUI mode
--version	—	Print version and exit

TUI mode

alice --tui

Launches a full-screen terminal interface built with Textual. Amber-on-black retro CRT aesthetic. Keyboard-driven: arrow keys to navigate, Enter to select, Escape to go back, q to quit.

Requires the tui extra: poetry install --extras tui

Recommended terminal font

For the intended look, set your terminal emulator's font to Source Code Pro or Fira Code. Both are free, open-source monospace fonts that pair well with the JHU brand palette. The TUI will display a hint on startup if it detects a different font (macOS only).

• Source Code Pro — Adobe's monospace companion to Source Sans/Serif
• Fira Code — monospace with programming ligatures

How JHED detection works

The CLI detects your JHED automatically from your active SSO session. It calls sts get-caller-identity, parses the assumed-role ARN to extract the session name (an email address), and takes the portion before @ as your JHED.

Secrets are keyed by {namespace}/{environment}/bedrock-api-keys/{jhed}@jhu.edu.

Project structure

alice-cli/
├── pyproject.toml
├── poetry.lock
└── src/alice_cli/
    ├── cli.py              # Click group, global options, command registration
    ├── commands/
    │   ├── auth.py         # alice auth [--claude]
    │   ├── get_key.py      # alice get-key [--eval|--env-file|--json]
    │   ├── invoke.py       # alice invoke
    │   ├── list_models.py  # alice list-models
    │   ├── list_aliases.py # alice list-aliases
    │   ├── get_secret.py   # alice get-secret [name]
    │   ├── list_secrets.py # alice list-secrets
    │   ├── run.py          # alice run <aws args...>
    │   ├── config_cmd.py   # alice config
    │   └── status.py       # alice status
    ├── auth.py             # JHED detection from STS
    ├── secrets.py          # Secrets Manager retrieval and validation
    ├── formatting.py       # Output formatters (export, eval, dotenv, json)
    ├── config.py           # Configuration resolution and precedence
    ├── store.py            # Persistent credential storage (~/.alice/)
    ├── console.py          # Rich console helpers (stderr output)
    ├── personality.py      # All user-facing text and messaging
    ├── validators.py       # Dependency checks (aws, jq, python version)
    ├── models.py           # Dataclasses, enums, model aliases
    ├── errors.py           # Error hierarchy (AuthError, SecretError, DependencyError)
    └── tui/                # Optional Textual TUI (requires extras)
        ├── app.py
        ├── theme.py
        ├── theme.tcss
        ├── screens/
        └── widgets/

Development

cd alice-cli
poetry install --extras tui

# Run tests
poetry run pytest

# Lint and format
poetry run ruff check .
poetry run ruff format .

# Type checking
poetry run mypy src/

Dev dependencies: pytest, hypothesis, pytest-mock, ruff, mypy, boto3-stubs.

Tests use Hypothesis for property-based testing (format correctness, config precedence, JHED extraction, secret path construction, AWS passthrough argument forwarding) alongside standard unit tests for error conditions and edge cases.

License

MIT