paw

name	paw
description	Use when running the Bun-backed Paw CLI: local health, active context, shell completions, output modes, profiles, and verification of the supported command surface.
paths	["packages/paw-cli/**","scripts/paw","justfile","specs/004-effect-paw-cli/**","specs/005-effect-cli-boundaries/**","specs/006-claude-agent-session-engine/**"]

paw

Use paw when you need the supported Pawrrtal CLI surface. This CLI is a Bun-backed Effect v4 package at packages/paw-cli; do not route new work through the deleted Python CLI.

Commands

Command	Aliases	Summary
paw doctor	-	Check local Paw CLI readiness
paw context	whoami	Print the active CLI context without secrets
paw completions <shell>	-	Generate shell completions

Common Usage

just paw --help
just paw doctor --json
just paw context --json
just paw whoami --plain
just paw completions zsh
bun run --filter @pawrrtal/cli start -- doctor

Global Options

Option	Meaning
-h, --help	Print help for the current command path
-V, --version	Print CLI version
-v, --verbose	Print expanded diagnostics and source chains
--profile	Run this invocation against a specific profile
--backend-url	Run this invocation against a specific backend target

Output Modes

• Human output is the default.
• --json prints schema-validated command data to stdout.
• --plain prints tab-separated rows to stdout when a command supports it.
• Progress, warnings, validation errors, runtime errors, and structured errors are rendered on stderr.
• --json and --plain are mutually exclusive.

Environment

• PAW_HOME: Override the CLI state root for config and cache.
• PAW_PROFILE: Set the active profile when --profile is not supplied.
• PAW_BACKEND_URL: Override the backend target for this invocation.
• XDG_CONFIG_HOME: Fallback config root when PAW_HOME is unset.
• XDG_CACHE_HOME: Fallback cache root when PAW_HOME is unset.

Exit Codes

Code	Meaning
0	Success
1	Internal, local, or config error
2	Usage, validation, or ambiguous input source
5	Backend, network, external process, or dependency failure

Verification

bun run --filter @pawrrtal/cli typecheck
bun run --filter @pawrrtal/cli test
bun run --filter @pawrrtal/cli check
bun run skill-gen:check
just paw-cli-check

Pitfalls

• -V prints the CLI version; -v enables verbose diagnostics.
• PAW_HOME overrides both config and cache roots for the invocation.
• paw context --json reports source labels such as flag, env:PAW_PROFILE, project:<path>, user:<path>, home-default, and unset.
• paw context and paw whoami must not print secret values.
• paw doctor is local-only in this slice and may warn when optional state has not been generated yet.