claude-cli

Overview

claude-cli is a provider-specific Rust CLI for Claude-oriented helpers that should not live in shell glue. The surface owns Claude Code prompt-segment rendering, usage source selection, Keychain credential lookup, cache fallback, and completion export.

Usage

Usage:
  claude-cli agent resume <SESSION_ID> [--cd <dir>]
  claude-cli prompt-segment [options]
  claude-cli prompt-segment check
  claude-cli prompt-segment status [--format text|json]
  claude-cli usage [--format text|json] [--source auto|oauth|cli|cache]
  claude-cli completion <bash|zsh>

Help:
  claude-cli help
  claude-cli agent --help
  claude-cli prompt-segment --help

Scope boundary

claude-cli owns provider-specific Claude behavior. zsh-kit should keep only the small compatibility wrapper and shell integration.

Commands

agent

• agent resume <SESSION_ID> [--cd <dir>]: Resolve the session's recorded working directory from local Claude Code project history and launch claude --resume <SESSION_ID> in that directory, propagating Claude's exit status. Claude Code has no --cd flag and stores sessions per project, so the recorded directory is applied as the child process working directory. Run it from any directory. Fails without launching Claude (65) when the id is unknown or matches more than one recorded directory; pass --cd to override the resolved directory for a repository that moved.

prompt-segment

• prompt-segment [--ttl <duration>] [--time-format <strftime>] [--refresh] [--is-enabled]: Render Claude 5h / weekly usage.
• prompt-segment check: Exit 0 when a Claude OAuth access token is available, otherwise 1.
• prompt-segment status [--format text|json]: Report readiness and cache state without exposing token material.

The output mirrors the former zsh-kit claude-prompt-segment helper:

5h:<remaining>% W:<remaining>% <weekly_reset_time>[<stale_suffix>]

The cache remains compatible with the former shell script:

~/Library/Caches/claude-prompt-segment/usage.json

usage

• usage [--format text|json] [--source auto|oauth|cli|cache]: Read Claude usage through a service-consumable contract.
• --source auto: Try OAuth usage refresh, then a bounded Claude CLI /usage probe, then last-good cache.
• --source oauth, --source cli, and --source cache: Run one source only for focused debugging.

JSON output uses schema_version: "claude-cli.usage.v1" and never includes tokens or credential material. The result includes provider: "claude" and a windows array containing 5h and weekly windows when available, each with used/remaining percentages and optional reset timestamps. CLI-derived usage is normalized back into the same cache shape used by prompt-segment.

completion

• completion <bash|zsh>: Export shell completion script to stdout.

Environment

• CLAUDE_PROMPT_TTL or CLAUDE_PROMPT_SEGMENT_TTL overrides the cache TTL. The default is 60 seconds. 0 forces refresh.
• CLAUDE_PROMPT_STALE_SUFFIX or CLAUDE_PROMPT_SEGMENT_STALE_SUFFIX controls stale cache suffix text. The default is one leading space followed by (stale).
• CLAUDE_PROMPT_SEGMENT_CACHE_DIR overrides the cache directory.
• CLAUDE_PROMPT_SEGMENT_ENDPOINT overrides the usage endpoint. The default is https://api.anthropic.com/api/oauth/usage.
• CLAUDE_PROMPT_SEGMENT_ACCESS_TOKEN or CLAUDE_PROMPT_SEGMENT_CREDENTIALS_JSON can supply credentials for automation.
• CLAUDE_PROMPT_SEGMENT_CLAUDE_BIN overrides the Claude CLI binary used by the usage --source cli fallback. The default is claude.
• CLAUDE_PROMPT_SEGMENT_CLAUDE_TIMEOUT_SECONDS overrides the bounded CLI usage probe timeout. The default is 15 seconds.
• CLAUDE_PROMPT_SEGMENT_CLAUDE_PTY_DISABLED=1 disables the Unix PTY wrapper and pipes slash commands directly to the Claude binary.
• CLAUDE_PROMPT_SEGMENT_CLAUDE_PTY_STARTUP_DELAY_MS and CLAUDE_PROMPT_SEGMENT_CLAUDE_PTY_USAGE_DELAY_MS tune the startup and post-/usage waits for interactive Claude Code. Defaults are 4000 and 3000 milliseconds.
• CLAUDE_PROMPT_SEGMENT_KEYCHAIN_DISABLED=1 disables macOS Keychain lookup.
• CLAUDE_PROMPT_SEGMENT_KEYCHAIN_SERVICE overrides the macOS Keychain service name. The default is Claude Code-credentials.
• NO_COLOR=1 disables ANSI color.

Dependencies

• macOS security is used for Keychain credential lookup unless an automation credential override is supplied.
• No curl, jq, or Python runtime is required for prompt-segment rendering.
• claude is required for agent resume.
• agent resume reads local Claude Code project history under $CLAUDE_CONFIG_DIR/projects (default ~/.claude/projects); the shared resolver lives in nils-provider-resume.

Exit codes

• 0: success, help output, or no prompt output needed.
• 1: operational false/failed state such as prompt-segment check without credentials.
• 64: usage or argument errors.
• 65: agent resume could not resolve the session id (unknown or ambiguous).

Docs

• Docs index