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
- Instale o CLI:
npm install -g envshed. - 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. - No Claude Code, rode
envshed agent install. Ele adiciona hooks que impedem o agente de ler arquivos.enve 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.
# 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
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-conflict | O que acontece com as chaves em conflito | Código de saída |
|---|---|---|
| não definido, sem terminal | Nada é gravado. Os nomes das chaves são listados. | 2 |
skip | Os valores atuais ficam. As chaves novas são gravadas. | 0 |
overwrite | Os valores do arquivo substituem os atuais. | 0 |
fail | Nada é 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
{
"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énullquando o arquivo não está num repositório git.ignoredLineslista os números das linhas do.envque não sãoKEY=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ódigo | Saída | Significado |
|---|---|---|
conflict | 2 | Há chaves com outro valor; nada foi gravado |
env_not_found | 1 | O ambiente não existe; adicione --create-env |
invalid_keys | 1 | Alguns nomes de chave não são só letras, dígitos e _; nada foi gravado |
file_not_found, format, parse | 1 | O arquivo não existe ou não pode ser lido |
usage | 1 | Flags que não podem ser usadas juntas, ou uma política desconhecida |
api | 1 | O 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: truequer 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: falsequer dizer que o arquivo não está no.gitignore. Adicione-o, ou apague o arquivo.- Quando
envshed run -- <comando>funcionar, o arquivo.envnão é mais necessário. Apagar ou não é decisão sua; o agente deve perguntar antes. - Rode
envshed scanpara 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 runmascara 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.