haru-cli 0.1.2

Secure, scriptable CLI for Amazon Bedrock Claude models via the AWS Strands Agents SDK.

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, 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
• AWS access via IAM Identity Center (SSO)

Install

pipx install haru-cli

Or from a clone:

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

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.

Development

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

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:

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.