ii999/agentenv

O que agentenv faz?

agentenv lê um arquivo de configuração TOML local que contém valores comuns e referências a credenciais. Os valores das credenciais residem em uma variável de ambiente, no armazém de credenciais da plataforma ou em um comando externo — nunca no arquivo. A CLI lê valores, edita o arquivo com gravações validadas que preservam a formatação e inicia processos alvo com valores selecionados injetados em um ambiente temporário.

Confirme que a CLI está disponível com command -v agentenv antes de depender dela. Se estiver faltando, informe e pare; não reconstrua seu comportamento lendo o arquivo de configuração diretamente.

Regras rígidas

• Nunca imprima, registre, persista ou resuma um valor de credencial resolvido. Não inicie agentenv run com um alvo escolhido para revelar seu próprio ambiente — env, printenv, set, sh -c 'echo $VAR' ou escrever o ambiente em um arquivo são todas violações.
• Nunca escreva um valor secreto no arquivo de configuração. set é para valores comuns; credential add escreve apenas uma definição; credential set é o único caminho que armazena um valor, e o armazena no armazém de credenciais da plataforma, não no arquivo.
• Se um perfil, entrada, campo ou credencial estiver faltando, reporte isso explicitamente. Não adivinhe um nome de campo, troque de perfil silenciosamente ou substitua outra credencial.
• Leia a configuração através da CLI, não abrindo o arquivo TOML, para que a seleção de perfil, indireção de credencial e validação se apliquem.
• Após credential fill escrever um valor em um campo do navegador, não leia esse campo de volta, avalie seu valor ou tire uma captura de tela que o mostre. O resultado do preenchimento é a única coisa que você pode reportar.

Lendo configuração

Trabalhe de cima para baixo; pule etapas que você já fez nesta sessão.

1. agentenv project status --json — descubra o arquivo de projeto mais próximo e seu estado de confiança antes de ler a configuração dependente de perfil. Seu relatório é escrito em stdout mesmo quando ele sai com código 5 ou 6; uma saída 2 deixa stdout vazio.
2. agentenv list --json — descubra perfis e entradas. agentenv list --profiles lista nomes de perfis sem selecionar um.
3. agentenv show <entry> --json — inspecione uma entrada desconhecida antes de usá-la. Campos de credencial aparecem como um membro reference (credential://<name> ou credential://<name>?as=<ENV>), nunca como um valor.
4. agentenv get <path> — leia um escalar comum. Use --json para um array ou tabela. Ler um campo de credencial retorna a string de referência, não o segredo.
5. agentenv find <needle> --json — procure nomes de entrada, nomes de campo, descrições e valores string quando você não sabe onde algo está. Adicione --all-profiles para pesquisar em todos os perfis.

Caminhos são segmentos de campo separados por ponto dentro do perfil selecionado, por exemplo llm.model. Coloque entre aspas um segmento contendo pontuação ou espaços: servers."my host".port. O perfil não faz parte do caminho; selecione-o com --profile <NAME> (precedência: --profile, depois AGENTENV_PROFILE, depois o pino do arquivo de projeto confiável, depois default_profile no arquivo). Isso se aplica a leituras, run, set e unset. --create-profile requer um --profile explícito e nunca usa o pino.

Configuração com escopo de projeto

agentenv descobre o arquivo .agentenv.toml regular mais próximo enquanto caminha do diretório de trabalho em direção à raiz do sistema de arquivos. O arquivo tem um esquema fechado, apenas de seleção: version = 1, um profile opcional não vazio e tabelas [requires.<entry>] opcionais com um reason não vazio e fields opcionais relativos à entrada que, quando presentes, são não vazios. É limitado a 64 KiB e não pode conter valores, definições de credencial, tabelas inject ou strings credential://.

Arquivos de projeto são inertes até que seu conteúdo exato seja aprovado. Use agentenv project status, agentenv project allow e agentenv project revoke para inspecionar, aprovar e remover aprovação. A aprovação é mantida no diretório de estado do usuário, fora do repositório; editar o arquivo o torna não confiável novamente. Um arquivo não confiável não afeta nenhum comando comum, exceto por um aviso em stderr.

Use --no-project, ou um AGENTENV_NO_PROJECT não vazio, para ignorar a descoberta para um comando fora do grupo project. A ignorância nunca se aplica a project status, project allow ou project revoke, que sempre descobrem o arquivo mais próximo.

project status --json escreve deliberadamente seu relatório em stdout com status de saída 5 para um estado de projeto indisponível, inválido ou não confiável e com status de saída 6 quando os requisitos não são atendidos ou não podem ser verificados. Esta é a exceção à regra usual de stdout vazio em caso de JSON com falha. Saída 2 cobre erros de configuração, incluindo erros de validação de arquivo de projeto, e deixa stdout vazio para este comando.

Executando um comando que precisa de credenciais

Use run com uma ou mais flags --with <entry> e o alvo após --:

agentenv run --with llm -- llm-client request
agentenv run --with llm --with kubernetes -- deploy-tool sync

Cada entrada --with contribui com suas referências de credencial e sua tabela inject (que mapeia nomes de ambiente para campos comuns dessa entrada). Uma credencial injeta sob seu nome inject_as, a menos que a referência carregue uma substituição ?as=<ENV>. Para saber quais nomes de ambiente um alvo receberá, leia inject_as de agentenv credential list --json e os membros inject e reference de agentenv show <entry> --json.

O stdin/stdout/stderr do alvo passam inalterados e seu status de saída é retornado. Injeções conflitantes (duas fontes visando um nome de ambiente) abortam com código de saída 4 antes que qualquer coisa resolva ou inicie.

Adicione --pure para iniciar o alvo com um ambiente mínimo curado: uma base de plataforma fixa (PATH, HOME, locale, AGENTENV_* e nomes similares críticos para o processo), mais variáveis carregadas explicitamente com --keep <NAME> repetível, mais as injeções — nada mais do shell de chamada. Um nome mantido não definido no pai é reportado em stderr e a execução continua. --pure filtra apenas o ambiente do alvo; não é uma sandbox, e chamadas agentenv aninhadas dentro do alvo ainda resolvem a mesma configuração. A resolução de credencial não é alterada por --pure: um subprocesso do provedor command mantém o ambiente pai completo.

Escrevendo configuração

Use estes quando o usuário pedir para registrar configuração:

agentenv init                            # cria o arquivo de configuração; recusa sobrescrever
agentenv set <path> <value>              # escreve um valor; cria tabelas intermediárias
agentenv set <path> <value> --type int|float|bool|json
agentenv set llm.model gpt-5 --description "LLM padrão."   # também cria a entrada
agentenv set <path> <value> --profile dev --create-profile "Perfil dev."
agentenv unset <path>                    # remove um campo ou tabela

Cada entrada precisa de uma descrição; criar uma nova entrada de nível superior requer --description no mesmo set. Um perfil desconhecido é um erro a menos que você passe --create-profile com um --profile explícito. Cada gravação é validada no arquivo inteiro primeiro e recusada se o resultado for inválido, então uma gravação rejeitada deixa o arquivo byte-idêntico — reporte o diagnóstico em vez de tentar variações cegamente.

A validação recusa valores de texto simples em campos string nomeados (ou com sufixo) token, password, secret, api_key ou private_key: tais campos devem conter uma referência credential://. Quando o usuário lhe entrega um segredo para salvar, defina e armazene-o como uma credencial (próxima seção) e então faça referência a ele.

Gerenciando credenciais

agentenv credential list --json          # definições + status superficial; não resolve nada
agentenv credential check <name>         # resolve uma credencial; reporta apenas disponibilidade
agentenv credential add <name> --description "<texto>" --provider env \
    --env-var <NAME> --inject-as <ENV>
agentenv credential add <name> --description "<texto>" --provider keychain \
    --service <service> --account <account> --inject-as <ENV>
agentenv credential add <name> --description "<texto>" --provider command \
    --argv <arg> [--argv <arg> ...] --inject-as <ENV>
agentenv credential set <name> --input dialog --json  # abre entrada local; aguarda seu resultado

Ordem para uma nova credencial: credential add a definição, então, para o provedor keychain, armazene o valor com credential set, depois faça referência a ele a partir de um campo de entrada como credential://<name>. Credenciais env e command obtêm seus valores de seus sistemas externos; credential set não se aplica a elas.

Para entrada de keychain local, execute credential set <name> --input dialog --json sem um PTY. Diga ao usuário para inserir o valor na janela local e salvar. Mantenha o comando em execução e aguarde sua conclusão, inclusive através de pausas de sessão de ferramenta; uma janela aberta não é um salvamento concluído. Nunca inspecione, capture, leia ou automatize a janela de entrada ativa ou a área de transferência. O usuário insere e verifica o valor lá, e o comando retorna apenas metadados de conclusão.

Continue a tarefa dependente apenas após saída 0 e JSON status: "stored". status: "cancelled" significa que a entrada terminou sem um salvamento confirmado; reporte e pare a ação dependente. status: "failed" inclui um reason não secreto; reporte o diagnóstico. store-unconfirmed significa que uma gravação pode ter ocorrido, então não afirme que o valor anterior não foi alterado ou repita automaticamente. Erros de inicialização/configuração podem sair antes que o JSON seja emitido; trate uma saída diferente de zero ou resultado ausente como falha. Um salvamento já em andamento termina antes do comando retornar; uma gravação confirmada reporta stored mesmo que o usuário tenha solicitado fechamento durante essa gravação.

O diálogo precisa de uma sessão gráfica na máquina executando agentenv. Em um host remoto ou sem cabeça, explique essa limitação e peça para o usuário executar agentenv credential set <name> --input terminal ele mesmo no terminal desse host e depois confirmar a conclusão. Não substitua por um PTY de propriedade do Agente ou pipe stdin. Nunca peça o valor no chat ou o coloque em argv, uma variável de ambiente, um pipe de comando ou um arquivo. A entrada de terminal suporta uma alternância de revelação local, então sua saída de tela deve permanecer fora das ferramentas do Agente.

Prefira provedores keychain ou command para uso local; env expõe o valor a todo processo que herda o ambiente e é adequado para CI.

Emparelhamento com Docker Compose

Mantenha configurações não secretas em .env. Injete credenciais apenas para o processo que precisa delas e então deixe o Compose receber a variável injetada:

agentenv run --with llm -- docker compose up

services:
  app:
    image: alpine:3.20
    environment:
      - OPENAI_API_KEY

A interpolação ${OPENAI_API_KEY} também é suportada pelo Compose. Não use um env_file: contendo segredos; ele persiste credenciais em um arquivo.

Preenchendo uma credencial em um campo de navegador

Use credential fill quando uma página que você está dirigindo precisar de uma credencial armazenada em um campo de entrada. Ele escreve o valor através do protocolo de depuração do navegador; você continua navegando e enviando com sua própria ferramenta de navegador.

agentenv credential fill --capabilities --json
agentenv credential fill <name> --backend cdp --endpoint http://127.0.0.1:<port> \
    --page-url <URL exata da página> --selector '<css do único campo>' --json

Passos:

1. Confirme que --capabilities lista o backend cdp como disponível. Seu navegador deve expor um endpoint do Chrome DevTools Protocol de loopback (um Chromium iniciado com --remote-debugging-port e um --user-data-dir não padrão, ou o endpoint que sua ferramenta de navegador já usa). Se não houver nenhum, informe; não inicie um navegador nem cole o valor.
2. Navegue para a página com sua ferramenta de navegador e então passe a URL exata da página e um seletor CSS que corresponda apenas ao campo alvo. Adicione --page-match origin-path quando a URL tiver parâmetros de consulta voláteis, --frame-selector para cada iframe no caminho até o campo, e --context-index se a mesma URL estiver aberta em vários contextos.
3. Feche DevTools nessa aba e mantenha rastreamento, screencasts, HAR e gravação de vídeo desligados enquanto preenche; agentenv falha apenas na janela DevTools aberta porque os outros gravadores não podem ser detectados.
4. Execute o comando. Sucesso imprime apenas {"version":1,"backend":"cdp","effect":"field-filled"}; o conteúdo anterior do campo foi substituído e a página recebeu eventos de entrada normais. Continue com sua própria ferramenta para enviar.

Apenas credenciais que permitem uso environment podem ser preenchidas; o valor deve ser uma única linha de no máximo 8.192 bytes sem caracteres de controle, separador de linha ou controle bidirecional (value-unsupported caso contrário). Um provedor command é executado sem terminal e sua nova linha final é removida; saída vazia, NUL ou não UTF-8 do provedor é um erro de credencial (saída 4). Toda a operação, incluindo um diálogo de autorização do keychain no primeiro acesso, executa sob --timeout-ms (padrão 30.000); aumente quando o usuário precisar clicar nesse diálogo. credential fill não verifica o campo, envia o formulário ou faz login; reporte o efeito, não um sucesso que você não observou.

Razões de falha em stderr (credential-fill: <reason>: <message>). Saída 8, nada mudou: backend-unavailable, permission, connect-failed, version-unsupported, recording-conflict, context-absent, page-absent, page-ambiguous, frame-absent, frame-ambiguous, frame-invalid, target-absent, target-ambiguous, target-hidden, target-disabled, target-readonly, target-unfillable, target-changed, value-unsupported, timeout, cancelled. Saída 11, o campo pode conter o valor: timeout, cancelled, ou delivery-failed após o valor ser enviado, e cleanup-unconfirmed após um valor entregue.

Execução privilegiada

Quando a solicitação usar um sudo-target configurado, leia references/sudo-execution.md antes de planejar, verificar, executar, criar ou girar esse alvo.