>_ ash

User commands · ash(1)

ash documentation

Practical shell assistant for command-not-found workflows. This page is the web version of the installable ash(1) man page.

Install on Debian or Ubuntu

See the APT installation guide for prerequisites, signing keys, repository setup, channels, updates, and removal.

Install on Fedora or RHEL-compatible Linux

See the DNF installation guide for prerequisites, metadata verification, repository setup, channels, updates, and removal.

Install on Arch Linux

See the Pacman installation guide for prerequisites, key verification, repository setup, channels, updates, and removal.

Synopsis

ash [text ...]
ash install [--shell bash|zsh] [--dry-run] [--overwrite]
ash mcp add <url> [--no-browser]
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 installs managed assets. Shell startup files are changed only when you explicitly request --shell-integration; Bash uses ~/.bashrc, zsh uses ~/.zshrc, and Fish uses $XDG_CONFIG_HOME/fish/config.fish.

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 follows XDG base directories: configuration and persistent workspace files under $XDG_CONFIG_HOME/ash (default ~/.config/ash), tools and plugins under $XDG_DATA_HOME/ash (default ~/.local/share/ash), history and session scratch under $XDG_STATE_HOME/ash (default ~/.local/state/ash), and cache under $XDG_CACHE_HOME/ash (default ~/.cache/ash). Broker sockets use $XDG_RUNTIME_DIR/ash with a state-directory fallback. Explicit XDG paths must be absolute.

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.

Remote MCP servers

MCP (Model Context Protocol) servers provide tools an AI model can call. Ash supports remote Streamable HTTP MCP servers and keeps their client sessions in ash-broker across Ash invocations in the same shell.

Register a trusted server by running ash mcp add <url> from an interactive Ash shell, or by adding its URL to $XDG_CONFIG_HOME/ash/.ash_allow (default ~/.config/ash/.ash_allow). No remote server is enabled by default.

OAuth authorization opens in the desktop browser when a GUI is available. If the browser cannot be opened, Ash prints a copyable authorization URL and waits in the terminal. Use ash mcp add <url> --no-browser to always use this terminal flow. Manual URL authorization still requires a browser on the same host; it is not a browserless OAuth flow.

URL lines beginning with http:// or https:// are MCP registrations, not shell commands. Schemes are recognized case-insensitively. Ash derives the server's local name from the first 8 lowercase hexadecimal characters of SHA-256 over the trimmed URL text. HTTPS is required except for localhost development; URLs with embedded credentials, query strings, or fragments are rejected. For direct OAuth connections, discovery permits non-public IP addresses only for the exact registered MCP authority; other OAuth hosts remain subject to non-public-address blocking. A configured egress proxy is responsible for filtering its destination addresses. Changes are read on the next Ash request.

MCP registrations remain enabled with ASH_STRICT=1. Returned tool output is still treated as untrusted evidence. Only register servers you trust: their tools may perform actions on your behalf. For OAuth-protected servers, Ash opens the browser when a GUI is available while the broker handles the callback and tokens. Credentials use the OS credential manager when available, or an encrypted file protected by a user-supplied random 32-byte ASH_MCP_CREDENTIAL_KEY in $XDG_DATA_HOME/ash/mcp/.

If MCP initialization fails, Ash continues the request without remote MCP tools. Interactive runs print a warning; non-interactive runs fail quietly. Scheduled jobs do not have the per-interactive-shell broker and therefore cannot use remote MCP tools. A scheduled prompt that depends on MCP may still run but can finish without the requested MCP action or data. Do not schedule prompts that require MCP.

See the MCP FAQ for a quick overview and setup notes.

Commands

ash [--attach path]... [text ...]
Run a single assistant request. --attach attaches a file (image or document) to the request; repeatable. Size-limited by ASH_ATTACHMENT_MAX_BYTES and currently sent on the wire only to OpenAI-compatible providers.
ash mcp add <url> [--no-browser]
Connect and register a remote MCP server in the effective .ash_allow. Opens OAuth authorization in a desktop browser when available; falls back to a copyable URL in the terminal. --no-browser always uses the terminal flow.
ash install [--shell bash|zsh|fish] [--shell-integration|--disable-shell-integration] [--dry-run]
Install assets without changing shell startup files by default. --shell-integration opts in to adding/updating the managed block; --disable-shell-integration removes only that block and preserves surrounding user content. When interactive, install auto-configures ASH_AI_ENDPOINT, ASH_AI_MODEL, and ASH_AI_AUTH_TOKEN when needed, preferring an existing provider key or local endpoint before showing a provider menu.
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, Linux, or FreeBSD release for the current architecture into ~/.local/bin/ash. Releases require Sigstore verification and SHA-256 verification.

Environment

ASH_AI_AUTH_TOKEN
Optional bearer token. Required for cloud endpoints except AWS Bedrock. Private/LAN addresses and .local hostnames are treated as non-cloud unless ASH_STRICT=1.
ASH_AI_CACHE
Optional provider-native cache toggle. Enabled by default when supported; accepts 1, true, yes, on, enabled, 0, false, no, off, or disabled (case-insensitive).
ASH_AI_ENDPOINT
Required base URL for the chat API endpoint.
ASH_AI_MODEL
Required model name sent to the endpoint.
ASH_AI_PROVIDER
Optional provider override. When unset, ash detects the provider from the endpoint.
ASH_AI_TIMEOUT
Optional request timeout. Default: 3m.
ASH_ALWAYS_OPENAI_API
Optional testing toggle. When true-like, routes the ollama provider through the OpenAI-compatible SDK adapter instead of its hand-rolled implementation. Accepts the same boolean values as ASH_AI_CACHE. Default: on.
ASH_ATTACHMENT_MAX_BYTES
Optional maximum size in bytes for a file passed via --attach. Default: 10485760 (10 MiB).
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_STREAM
Optional toggle. When true-like, streams the response from providers whose adapter supports it (currently OpenAI only). Accepts the same boolean values as ASH_AI_CACHE. Default: on.
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_ALLOW
Optional comma-separated executable allowlist for run_unix_command. Otherwise $XDG_CONFIG_HOME/ash/.ash_allow (default ~/.config/ash/.ash_allow) is used; this override does not expand internal Ash tokens.
ASH_DENY
Optional comma-separated denylist for explicitly blocking commands, tools, and plugins. Otherwise $XDG_CONFIG_HOME/ash/.ash_deny (default ~/.config/ash/.ash_deny) is used.
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.
ASH_SESSION_ID
Ash session identifier for persistent history and log naming. Generated when absent; invalid explicit values are rejected. Generic SESSION_ID is ignored.

Explicit numeric and duration settings are validated. Integer limits must be positive except ASH_MAX_TOOL_ITERS, which may be zero. AI/tool timeouts must be positive; retry delays may be zero but not negative. Durations use Go syntax such as 30s, 5m, or 1h. Malformed or out-of-range values produce a configuration error instead of silently using defaults.

Files

  • $XDG_CONFIG_HOME/ash/ (default ~/.config/ash/) — canonical prompt, policy, and persistent workspace files.
  • $XDG_DATA_HOME/ash/ (default ~/.local/share/ash/) — bundled tools, plugins, language packs, and MCP credentials.
  • $XDG_STATE_HOME/ash/ (default ~/.local/state/ash/) — history, scratch, logs, and snooze state.
  • $XDG_CACHE_HOME/ash/ (default ~/.cache/ash/) — regenerable cache files.

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

See also

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

Source: docs/ash.1 · README · Security policy