ashdocumentação

Instalar no Debian ou Ubuntu

Veja oGuia de instalação do APTpara pré-requisitos, chaves de assinatura, configuração de repositório, canais, atualizações e remoção.

Instale no Fedora ou Linux compatível com RHEL

Veja oGuia de instalação DNFpara pré-requisitos, verificação de metadados, configuração de repositório, canais, atualizações e remoção.

Instalar no Arch Linux

Veja oGuia de instalação do Pacmanpara pré-requisitos, verificação de chave, configuração de repositório, canais, atualizações e remoção.

Sinopse

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]

Descrição

ashenvia texto de prompt para o endpoint de IA configurado e imprime a resposta do assistente. Quando nenhum texto posicional é fornecido,ashlê o texto do prompt da entrada padrão não interativa.

OinstallO subcomando instala ativos gerenciados. Os arquivos de inicialização do shell são alterados somente quando você solicita explicitamente--shell-integration; Bash usa~/.bashrc, zsh usa~/.zshrc, e peixes usam$XDG_CONFIG_HOME/fish/config.fish.

As conexões com o provedor de IA são compartilhadas por meio de um corretor local. A falha do corretor recorre ao HTTPS direto.

A IA pode usar o systemd para agendar tarefas em segundo plano. Podem ser trabalhos recorrentes ou pontuais. Os trabalhos agendados usam HTTPS direto por padrão.

ashsegue os diretórios base do XDG: arquivos de configuração e de espaço de trabalho persistente em$XDG_CONFIG_HOME/ash(padrão~/.config/ash), ferramentas e plug-ins em$XDG_DATA_HOME/ash(padrão~/.local/share/ash), histórico e sessão zero em$XDG_STATE_HOME/ash(padrão~/.local/state/ash) e cache em$XDG_CACHE_HOME/ash(padrão~/.cache/ash). Uso de soquetes de corretor$XDG_RUNTIME_DIR/ashcom um substituto do diretório de estado. Os caminhos XDG explícitos devem ser absolutos.

A saída de ferramenta, script, arquivo, canal e filho são dados não confiáveis ​​e não devem substituir as instruções do sistema ou do usuário. O recurso de execução da ferramenta não é um sandbox quando a execução arbitrária de Python ou shell está habilitada. Por padrão, o Python está habilitado, então tome cuidado.

Servidores MCP remotos

Os servidores MCP (Model Context Protocol) fornecem ferramentas que um modelo de IA pode chamar.Ashsuporta servidores Streamable HTTP MCP remotos e mantém suas sessões de cliente emash-brokerentreAshinvocações no mesmo shell.

Registre um servidor confiável executandoash mcp add <url>de um interativoAshshell ou adicionando seu URL ao$XDG_CONFIG_HOME/ash/.ash_allow(padrão~/.config/ash/.ash_allow). Nenhum servidor remoto está habilitado por padrão.

A autorização OAuth é aberta no navegador do desktop quando uma GUI está disponível. Se o navegador não puder ser aberto,Ashimprime um URL de autorização copiável e espera no terminal. Usarash mcp add <url> --no-browserpara sempre usar esse fluxo de terminal. A autorização manual de URL ainda requer um navegador no mesmo host; não é um fluxo OAuth sem navegador.

Linhas de URL começando comhttp://ouhttps://são registros MCP, não comandos shell. Os esquemas são reconhecidos sem distinção entre maiúsculas e minúsculas.Ashderiva o nome local do servidor dos primeiros 8 caracteres hexadecimais minúsculos de SHA-256 no texto do URL cortado. HTTPS é necessário, exceto para desenvolvimento de localhost; URLs com credenciais incorporadas, strings de consulta ou fragmentos são rejeitados. Para conexões OAuth diretas, a descoberta permite endereços IP não públicos apenas para a autoridade MCP registrada exata; outros hosts OAuth permanecem sujeitos ao bloqueio de endereços não públicos. Um proxy de saída configurado é responsável por filtrar seus endereços de destino. As alterações serão lidas no próximoAshsolicitar.

Os registros do MCP permanecem habilitados comASH_STRICT=1. A saída da ferramenta retornada ainda é tratada como evidência não confiável. Registre apenas servidores em que você confia: suas ferramentas podem realizar ações em seu nome. Para servidores protegidos por OAuth,Ashabre o navegador quando uma GUI está disponível enquanto o corretor lida com o retorno de chamada e os tokens. As credenciais usam o gerenciador de credenciais do sistema operacional, quando disponível, ou um arquivo criptografado protegido por um arquivo aleatório de 32 bytes fornecido pelo usuário.ASH_MCP_CREDENTIAL_KEYem$XDG_DATA_HOME/ash/mcp/.

Se a inicialização do MCP falhar,Ashcontinua a solicitação sem ferramentas MCP remotas. As execuções interativas imprimem um aviso; execuções não interativas falham silenciosamente.Os trabalhos agendados não possuem o agente de shell interativo por pessoa e, portanto, não podem usar ferramentas MCP remotas.Um prompt agendado que depende do MCP ainda pode ser executado, mas pode ser concluído sem a ação ou os dados do MCP solicitados. Não agende prompts que exijam MCP.

Veja oPerguntas frequentes sobre PCMpara uma visão geral rápida e notas de configuração.

Comandos

ash [--attach path]... [text ...]

Execute uma única solicitação de assistente.--attachanexa um arquivo (imagem ou documento) à solicitação; repetível. Tamanho limitado porASH_ATTACHMENT_MAX_BYTESe atualmente enviado por transferência apenas para provedores compatíveis com OpenAI.

ash mcp add <url> [--no-browser]

Conecte e registre um servidor MCP remoto no efetivo.ash_allow. Abre a autorização OAuth em um navegador de desktop, quando disponível; recorre a um URL copiável no terminal.--no-browsersempre usa o fluxo terminal.

ash install [--shell bash|zsh|fish] [--shell-integration|--disable-shell-integration] [--dry-run]

Instale ativos sem alterar os arquivos de inicialização do shell por padrão.--shell-integrationopta por adicionar/atualizar o bloco gerenciado;--disable-shell-integrationremove apenas esse bloco e preserva o conteúdo do usuário ao redor. Quando interativo, instale configurações automáticasASH_AI_ENDPOINT,ASH_AI_MODEL, eASH_AI_AUTH_TOKENquando necessário, preferindo uma chave de provedor existente ou um endpoint local antes de mostrar um menu de provedor.

ash snooze [duration|off]

Pause o processamento automático do prompt do shell. O padrão é cinco minutos. As durações usam a sintaxe Go, como30s,5m, ou1h. Usaroffpara retomar imediatamente.

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

Baixe e instale a versão estável mais recente do macOS, Linux ou FreeBSD para a arquitetura atual em~/.local/bin/ash. As versões exigem verificação Sigstore e verificação SHA-256.

Meio Ambiente

ASH_AI_AUTH_TOKEN

Token ao portador opcional. Obrigatório para endpoints de nuvem, exceto AWS Bedrock. Endereços privados/LAN e.localnomes de host são tratados como não-nuvem, a menos queASH_STRICT=1.

ASH_AI_CACHE

Alternação opcional do cache nativo do provedor. Ativado por padrão quando compatível; aceita1,true,yes,on,enabled,0,false,no,off, oudisabled(não diferencia maiúsculas de minúsculas).

ASH_AI_ENDPOINT

URL base necessária para o endpoint da API de chat.

ASH_AI_MODEL

Nome do modelo obrigatório enviado ao endpoint.

ASH_AI_PROVIDER

Substituição opcional do provedor. Quando não definido,ashdetecta o provedor do endpoint.

ASH_AI_TIMEOUT

Tempo limite de solicitação opcional. Padrão:3m.

ASH_ALWAYS_OPENAI_API

Alternância de teste opcional. Quando verdadeiro, roteia oollamaprovedor por meio do adaptador SDK compatível com OpenAI em vez de sua implementação manual. Aceita os mesmos valores booleanos queASH_AI_CACHE. Padrão: ativado.

ASH_ATTACHMENT_MAX_BYTES

Tamanho máximo opcional em bytes para um arquivo passado via--attach. Padrão:10485760(10 MiB).

ASH_HISTORY_MAX

Máximo opcional de mensagens de histórico por chave. Padrão:40.

ASH_LOG_FILE

Caminho de log de depuração opcional quando o log detalhado está habilitado.

ASH_LOG_MAX_BYTES

Tamanho máximo de log opcional antes da rotação. Padrão:1048576.

ASH_MAX_AGENTS

Máximo opcional de subagentes gerados por um processo pai. Padrão:6.

ASH_MAX_TOOL_ITERS

Iterações máximas opcionais do loop de chamada de ferramenta de IA. Padrão:16.

ASH_RELEVANCE_WINDOW

Observações recentes opcionais da ferramenta incluídas no estado de execução. Padrão:4.

ASH_RETRY_BASE_DELAY

Atraso base de espera de nova tentativa opcional. Padrão:250ms.

ASH_RETRY_MAX_ATTEMPTS

Tentativas opcionais de solicitação repetíveis. Padrão:3.

ASH_SCHEDULED_TASK

Sinalizador de agendador interno usado porashinvocações gerenciadas.

ASH_STREAM

Alternar opcional. Quando verdadeiro, transmite a resposta dos provedores cujo adaptador oferece suporte (atualmente apenas OpenAI). Aceita os mesmos valores booleanos queASH_AI_CACHE. Padrão: ativado.

ASH_TASK_MAX

Limite opcional nas tarefas de execução derivadas de uma solicitação. Padrão:6.

ASH_TASK_STALL_ROUNDS

Assistente opcional para rodadas antes de parar. Padrão:2.

ASH_ALLOW

Lista de permissões executável separada por vírgula opcional pararun_unix_command. De outra forma$XDG_CONFIG_HOME/ash/.ash_allow(padrão~/.config/ash/.ash_allow) é usado; esta substituição não expande internamenteAshfichas.

ASH_DENY

Lista de bloqueio opcional separada por vírgula para bloquear explicitamente comandos, ferramentas e plug-ins. De outra forma$XDG_CONFIG_HOME/ash/.ash_deny(padrão~/.config/ash/.ash_deny) é usado.

ASH_TOOL_OUTPUT_MAX

Saída máxima opcional da ferramenta capturada em bytes. Padrão:8192.

ASH_TOOL_TIMEOUT

Tempo limite de comando da ferramenta local opcional. Padrão:15s.

ASH_VERBOSE

Log de depuração opcional e painel de execução. Valores como1,true,on, edebugativá-lo.

ASH_SESSION_ID

Ashidentificador de sessão para histórico persistente e nomeação de log. Gerado quando ausente; valores explícitos inválidos são rejeitados. GenéricoSESSION_IDé ignorado.

As configurações numéricas e de duração explícitas são validadas. Os limites inteiros devem ser positivos, excetoASH_MAX_TOOL_ITERS, que pode ser zero. Os tempos limite da IA/ferramenta devem ser positivos; atrasos de novas tentativas podem ser zero, mas não negativos. As durações usam a sintaxe Go, como30s,5m, ou1h. Valores malformados ou fora do intervalo produzem um erro de configuração em vez de usar padrões silenciosamente.

Arquivos

• $XDG_CONFIG_HOME/ash/(padrão~/.config/ash/)—prompt canônico, política e arquivos de espaço de trabalho persistentes.
• $XDG_DATA_HOME/ash/(padrão~/.local/share/ash/)—ferramentas incluídas, plug-ins, pacotes de idiomas e credenciais MCP.
• $XDG_STATE_HOME/ash/(padrão~/.local/state/ash/)—histórico, zero, registros e estado de soneca.
• $XDG_CACHE_HOME/ash/(padrão~/.cache/ash/)—arquivos de cache regeneráveis.

Status de saída

ash retorna 0 em caso de sucesso. Ele retorna diferente de zero quando a configuração, as solicitações de rede ou a execução da ferramenta falham.

Exemplos

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

Veja também

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