Pular para o conteúdo principal

Migre um projeto existente com um agente de IA

Um agente de código, como o Claude Code ou o Cursor, consegue mover sozinho os arquivos .env de um projeto para o Envshed. Ele cria o projeto, vincula a pasta, importa cada arquivo para o ambiente certo e inicia o app com os segredos injetados.

O agente nunca lê um valor. O CLI lê os arquivos na sua máquina e manda os valores ao Envshed com o seu login. O agente vê nomes de chaves, contagens e códigos de saída.

Antes de começar​

  1. Instale o CLI: npm install -g envshed.
  2. Entre na sua conta você mesmo, no seu terminal: envshed login. O agente usa esse login. Não é uma credencial separada do agente, então a importação tem as suas permissões.
  3. No Claude Code, rode envshed agent install. Ele adiciona hooks que impedem o agente de ler arquivos .env e uma skill com estes passos. Veja Agent hooks.

O que o agente roda​

Troque <org>, <project> e os nomes de arquivos e ambientes pelos seus.

terminal
# 1. Escolha a organização e crie o projeto, se precisar
envshed orgs
envshed projects -o <org>
envshed project create --name <project> -o <org> --output json

# 2. Vincule esta pasta (grava o .envshed.json, que pode ir para o git)
envshed init -o <org> -p <project> -e development --yes --no-guide --no-import

# 3. Planeje cada arquivo: só nomes de chaves, nada é gravado
envshed import .env -e development --dry-run --output json
envshed import .env.production -e production --dry-run --output json

# 4. Importe, com uma escolha explícita para as chaves que já existem
envshed import .env -e development --on-conflict skip --output json
envshed import .env.production -e production --on-conflict skip --output json

# 5. Inicie o app com os segredos injetados
envshed run -- npm run dev

O envshed init também importa os arquivos que encontra (--import --import-map .env=development,.env.production=production). Para um agente, o envshed import separado é melhor: ele tem simulação, política de conflito e saída em JSON.

Um prompt para dar ao agente​

output
Mova as variáveis de ambiente deste projeto para o Envshed.
Organização: <org>. Nome do projeto: <project>.
Mapeie .env para development e .env.production para production.
Siga os passos "Moving a project's env files into Envshed" da skill envshed-agent-safety.
Use --dry-run e --output json primeiro. Se alguma chave já existir com outro valor, pare e me pergunte.
Nunca leia nem mostre os arquivos .env. Não apague os arquivos; me avise quando o app rodar com envshed run.

Conflitos​

Uma chave "conflita" quando já existe no ambiente com outro valor. Sem terminal, o envshed import nunca pergunta e nunca sobrescreve por conta própria:

--on-conflictO que acontece com as chaves em conflitoCódigo de saída
não definido, sem terminalNada é gravado. Os nomes das chaves são listados.2
skipOs valores atuais ficam. As chaves novas são gravadas.0
overwriteOs valores do arquivo substituem os atuais.0
failNada é gravado.2

Chaves com o mesmo valor nunca são enviadas de novo. O --force grava todas as chaves sem ler o ambiente antes. Prefira --on-conflict overwrite, que informa o que mudou.

A saída em JSON​

json
{
"target": { "org": "acme", "project": "api", "env": "development" },
"file": ".env",
"dryRun": false,
"policy": "skip",
"environmentCreated": false,
"ignoredLines": [],
"keys": {
"new": ["DATABASE_URL"],
"changed": ["API_KEY"],
"unchanged": ["PORT"],
"skipped": ["API_KEY"],
"written": ["DATABASE_URL"]
},
"git": { "tracked": false, "ignored": false }
}
  • git é null quando o arquivo não está num repositório git.
  • ignoredLines lista os números das linhas do .env que não são KEY=value, comentários ou linhas em branco. Elas são puladas, e o mesmo aviso vai para o stderr. O conteúdo delas nunca aparece: peça ao usuário para corrigir essas linhas.

Num erro, o JSON é { "error": "<code>", "message": "...", "keys": [...] }. Em conflict, keys lista as chaves em conflito. Em invalid_keys, lista os nomes inválidos (um nome que parece um valor é contado, não mostrado).

CódigoSaídaSignificado
conflict2Há chaves com outro valor; nada foi gravado
env_not_found1O ambiente não existe; adicione --create-env
invalid_keys1Alguns nomes de chave não são só letras, dígitos e _; nada foi gravado
file_not_found, format, parse1O arquivo não existe ou não pode ser lido
usage1Flags que não podem ser usadas juntas, ou uma política desconhecida
api1O servidor recusou o pedido

Um ambiente que não existe aparece como env_not_found. Adicione --create-env para criá-lo, ou rode envshed env create antes.

Depois da importação​

  • git.tracked: true quer dizer que o arquivo está no git, então os valores estão no histórico do repositório. Tire o arquivo do git e faça a rotação desses segredos.
  • git.ignored: false quer dizer que o arquivo não está no .gitignore. Adicione-o, ou apague o arquivo.
  • Quando envshed run -- <comando> funcionar, o arquivo .env não é mais necessário. Apagar ou não é decisão sua; o agente deve perguntar antes.
  • Rode envshed scan para procurar esses valores nos históricos locais dos agentes.

Contra o que isto não protege​

  • O agente roda com o seu login. Ele pode fazer o que você faz com o CLI, inclusive rodar comandos que mostram valores, como envshed secret get. Os hooks do Claude Code bloqueiam os conhecidos, e outros agentes não têm hooks. Veja What this does not protect against.
  • O envshed run mascara os valores na saída do comando, mas um programa que transforma um valor ou o grava num arquivo passa pela máscara.
  • As mensagens de erro da leitura do arquivo mostram no máximo um número de linha, nunca o conteúdo. As mensagens do servidor podem citar chaves, nunca valores.
  • O servidor MCP não cria projetos nem importa arquivos, porque nunca lida com valores. Use o CLI.