ash documentation

Synopsis

ash [text ...]
ash install [--shell bash|zsh|pwsh] [--dry-run] [--overwrite]
ash snooze [duration|off]
ash update [--version vX.Y.Z] [--yes|--skip-customized]

Description

ash sends prompt text to the configured AI endpoint and prints the assistant response. When no positional text is provided, ash reads prompt text from non-interactive standard input.

The install subcommand adds a managed integration block to shell startup files. Bash uses ~/.bashrc, and zsh uses ~/.zshrc.

Connections to the AI provider are shared through a local broker. Broker failure falls back to direct HTTPS.

The AI can use systemd to schedule background tasks. These can be recurring or one-off jobs. Scheduled jobs use direct HTTPS by default.

ash maintains a session-scoped scratch workspace under ~/.ash/scratch/<session-id>/. Stale and idle scratch directories are removed automatically after the configured retention window. The history logs are stored under ~/.ash/history/. Old history files are automatically cleaned up according to the retention policy.

Tool, script, file, piped, and child output is untrusted data and must not override system or user instructions. The tool execution feature is not a sandbox when arbitrary Python or shell execution is enabled. By default Python is enabled, so beware.

Commands

ash [text ...]

Run a single assistant request.

ash install [--shell bash|zsh|pwsh] [--dry-run]

Install or update shell integration. When --shell is omitted, the current shell is used when possible and PowerShell defaults to pwsh on Windows. --dry-run previews changes without writing.

ash snooze [duration|off]

Pause automatic shell prompt processing. The default is five minutes. Durations use Go syntax such as 30s, 5m, or 1h. Use off to resume immediately.

ash update [--version vX.Y.Z] [--yes|--skip-customized]

Download and install the latest stable macOS or Linux release for the current architecture into ~/go/bin/ash. Releases require Sigstore verification and SHA-256 verification. Windows updates are not supported.

Environment

AI_AUTH_TOKEN

Optional bearer token. When set, it is sent as bearer authentication and is required for cloud endpoints.

AI_CACHE

Optional provider-native cache toggle. Enabled by default when supported; use off or false to disable.

AI_ENDPOINT

Required base URL for the chat API endpoint.

AI_MODEL

Required model name sent to the endpoint.

AI_PROVIDER

Optional provider override: anthropic, gemini, google, ollama, or openai. When unset, ash detects the provider from the endpoint.

AI_TIMEOUT

Optional request timeout. Default: 3m.

ASH_HISTORY_MAX

Optional maximum history messages per key. Default: 40.

ASH_LOG_FILE

Optional debug log path when verbose logging is enabled.

ASH_LOG_MAX_BYTES

Optional maximum log size before rotation. Default: 1048576.

ASH_MAX_AGENTS

Optional maximum sub-agents generated by one parent process. Default: 6.

ASH_MAX_TOOL_ITERS

Optional maximum AI tool-call loop iterations. Default: 16.

ASH_RELEVANCE_WINDOW

Optional recent tool observations included in execution state. Default: 4.

ASH_RETRY_BASE_DELAY

Optional retry backoff base delay. Default: 250ms.

ASH_RETRY_MAX_ATTEMPTS

Optional retryable request attempts. Default: 3.

ASH_SCHEDULED_TASK

Internal scheduler flag used by ash-managed invocations.

ASH_TASK_MAX

Optional cap on execution tasks derived from a request. Default: 6.

ASH_TASK_STALL_ROUNDS

Optional assistant stall rounds before stopping. Default: 2.

ASH_TOOL_ALLOWLIST

Optional comma-separated executable allowlist for run_unix_command. Otherwise ~/.ash/.ash_tools is used when present.

ASH_TOOL_OUTPUT_MAX

Optional maximum captured tool output in bytes. Default: 8192.

ASH_TOOL_TIMEOUT

Optional local tool command timeout. Default: 15s.

ASH_VERBOSE

Optional debug logging and execution dashboard. Values such as 1, true, on, and debug enable it.

SESSION_ID

Session identifier for persistent history and log naming. Generated automatically for interactive runs when missing.

Files

• ~/.ash/.ash_system — canonical system prompt.
• ~/.ash/.ash_tools — canonical tool allowlist.
• ~/.ash/history/ — conversation history files.
• ~/.ash/scratch/ — session-scoped scratch files.
• ~/.ash/.ash_snooze_until — automatic prompt snooze expiry.

Exit status

ash returns 0 on success. It returns non-zero when configuration, network requests, or tool execution fail.

Examples

echo "summarize this directory" | ash
ash install --shell bash
ash install --shell zsh --dry-run
ash install --shell pwsh

See also

bash(1), zsh(1), pwsh(1), man(1)