Metadata-Version: 2.4
Name: haru-cli
Version: 0.1.2
Summary: Secure, scriptable CLI for Amazon Bedrock Claude models via the AWS Strands Agents SDK.
Author: haru-cli maintainers
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,bedrock,claude,cli,strands
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.13
Requires-Dist: boto3>=1.43.0
Requires-Dist: botocore>=1.43.0
Requires-Dist: click>=8.2.0
Requires-Dist: opentelemetry-exporter-otlp>=1.27.0
Requires-Dist: opentelemetry-sdk>=1.27.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.9.0
Requires-Dist: strands-agents-tools>=0.2.0
Requires-Dist: strands-agents>=1.42.0
Description-Content-Type: text/markdown

# haru-cli

A secure, scriptable command line interface for interacting with Amazon Bedrock Claude models
through governed, observable, multi-agent workflows. haru-cli is a thin, functional orchestration
layer over the [AWS Strands Agents SDK](https://strandsagents.com), talking to Bedrock through the
Converse API with streaming, tool use, MCP client support, multi-agent orchestration, session
persistence, OpenTelemetry observability, and Bedrock Guardrails.

## Requirements

- Python 3.13+ (tested on 3.13 and 3.14)
- [uv](https://docs.astral.sh/uv/)
- AWS access via IAM Identity Center (SSO)

## Install

```bash
pipx install haru-cli
```

Or from a clone:

```bash
uv sync
```

## Commands

| Command                          | Purpose                                                       |
| -------------------------------- | ------------------------------------------------------------- |
| `haru config init`               | Create a starter configuration (interactive)                  |
| `haru config show`               | Show the resolved configuration (no secrets)                  |
| `haru login`                     | Browser sign-in to IAM Identity Center (OAuth 2.0 + PKCE)     |
| `haru chat`                      | Interactive streaming chat REPL                               |
| `haru chat --session-id <id>`    | Persist and restore the conversation under a session id       |
| `haru chat --agent <name>`       | Chat with a specific configured agent                         |
| `haru run "<prompt>"`            | One-shot prompt; prints the answer and exits                  |
| `haru agents`                    | List configured agents (model, prompt, tools, MCP)            |
| `haru session list`              | List stored session ids                                       |
| `haru --version`                 | Print the installed version                                   |

Configuration is resolved from `--config`, then `$HARU_CONFIG`, then
`./config/haru.yaml`, then `~/.config/haru/haru.yaml`.

Inside `haru chat`, slash commands switch targets mid-session:

| REPL command     | Purpose                                                    |
| ---------------- | ---------------------------------------------------------- |
| `/help`          | Show REPL commands                                         |
| `/model`         | List configured models (default and active marked)         |
| `/model <name>`  | Switch the default agent to that model (resets the chat)   |
| `/agent`         | List configured agents                                     |
| `/agent <name>`  | Switch to that agent (resets the chat)                     |

## Quickstart

```bash
haru config init      # writes ~/.config/haru (asks for your SSO start URL)
export HARU_AWS_ACCOUNT_ID=<your AWS account id>
haru login
haru run "Summarise the Converse API in two sentences."
haru chat --agent supervisor --session-id demo
```

Authentication uses the same PKCE authorization-code flow as `aws sso login`,
caching tokens in the botocore-compatible schema under `~/.aws/sso/cache`
(0600) so standard AWS tooling can consume and refresh the same cache. Access
tokens are refreshed automatically; when a fresh login is needed, commands say
so plainly.

## Sampling controls

haru-cli exposes `temperature`, `top_p`, `top_k`, and `seed` on **three
configuration surfaces** — a capability Kiro CLI does not offer on any of its
configuration surfaces (its v2/v3 agent formats and `cli.json` define no
sampling fields):

| Surface                  | Where                                          | Example                                   |
| ------------------------ | ---------------------------------------------- | ----------------------------------------- |
| Model catalogue          | `models.yaml`, per model entry                 | `temperature: 0.2`, `top_k: 50`           |
| Agent profile            | `agents.yaml`, per agent `sampling:` block     | `sampling: {temperature: 0.1}`            |
| CLI / REPL               | `--temperature/--top-p/--top-k/--seed` flags on `run` and `chat`; `/sampling` in the REPL | `haru run "..." --top-k 20` |

Precedence: **CLI/REPL override → agent `sampling:` block → model entry**,
merged per-field. Unset fields are omitted from requests entirely, keeping
the provider's defaults. In the chat REPL, `/sampling` shows the model
default, session override, and effective value for each field;
`/sampling temperature=0.2 top_k=50` applies overrides and `/sampling reset`
clears them.

Model compatibility (AWS-side behaviour, not a haru limitation):

- **Claude 5-series and Opus 4.7+** (Sonnet 5, Opus 5, Opus 4.8) reject
  non-default `temperature`/`top_p`/`top_k` with an HTTP 400 — leave them
  unset on those entries (the shipped config does).
- **Claude Haiku 4.5, Sonnet 4.5, and older Claude models**, plus
  non-Anthropic Bedrock models, accept them.
- `seed` is forwarded via Converse `additionalModelRequestFields` for Bedrock
  models that support it; **no Claude model accepts a seed today**, so do not
  expect determinism from Claude — the field exists for models that honour it.

## Configuration

Declarative YAML under `config/` — models, agents, orchestration
(supervisor/swarm/graph), MCP servers, guardrails, sessions, sampling,
logging, and OpenTelemetry. No secrets in YAML: values reference environment
variables with `${env:VAR}`. See [docs/configuration.md](docs/configuration.md).

## Development

All quality gates must pass before a change is considered done:

```bash
uv run ruff check
uv run ruff format
uv run mypy src
uv run pytest
```

Coverage is gated at 90% (`--cov-fail-under=90`). CI runs the full gate set on
Python 3.13 and 3.14; releases are built with `uv build` and published to PyPI
via Trusted Publishing on `v*` tags.

Install the pre-commit hooks once per clone:

```bash
uv tool run pre-commit install
```

## Project layout

- `src/haru/` — the package (auth, config, models, agents, tools, steering, sessions, observability, commands)
- `config/` — declarative YAML configuration and steering prompts
- `tests/unit`, `tests/integration` — pytest suites (coverage gate: 90%)
- `.kiro/steering/` — authoritative engineering steering documents

## License

Apache-2.0. See [LICENSE](LICENSE).
