Migrate an existing project with an AI agent
A coding agent such as Claude Code or Cursor can move a project's .env files into Envshed on its own: create the project, link the folder, import each file into the right environment and start the app with the secrets injected.
The agent never reads a value. The CLI reads the files on your machine and sends the values to Envshed under your login; the agent sees key names, counts and exit codes.
Before you start
- Install the CLI:
npm install -g envshed. - Sign in yourself, in your own terminal:
envshed login. The agent uses this login. It is not a separate agent credential, so the import has your permissions. - For Claude Code, run
envshed agent install. It adds hooks that stop the agent from reading.envfiles and a skill with these steps. See Agent hooks.
What the agent runs
Replace <org>, <project> and the file and environment names with yours.
# 1. Pick the organization and create the project if needed
envshed orgs
envshed projects -o <org>
envshed project create --name <project> -o <org> --output json
# 2. Link this folder (writes .envshed.json, safe to commit)
envshed init -o <org> -p <project> -e development --yes --no-guide --no-import
# 3. Plan each file: key names only, nothing is written
envshed import .env -e development --dry-run --output json
envshed import .env.production -e production --dry-run --output json
# 4. Import, with an explicit choice for keys that already exist
envshed import .env -e development --on-conflict skip --output json
envshed import .env.production -e production --on-conflict skip --output json
# 5. Start the app with the secrets injected
envshed run -- npm run dev
envshed init can also import the files it finds (--import --import-map .env=development,.env.production=production). The separate envshed import step is better for an agent: it has a dry run, a conflict policy and JSON output.
A prompt you can give the agent
Move this project's environment variables into Envshed.
Organization: <org>. Project name: <project>.
Map .env to development and .env.production to production.
Follow the "Moving a project's env files into Envshed" steps of the envshed-agent-safety skill.
Use --dry-run and --output json first. If any key already exists with another value, stop and ask me.
Never read or print the .env files. Do not delete them; tell me when the app runs with envshed run.
Conflicts
A key "conflicts" when it already exists in the environment with another value. Without a terminal, envshed import never asks and never overwrites on its own:
--on-conflict | What happens to conflicting keys | Exit code |
|---|---|---|
| not set, no terminal | Nothing is written. The key names are listed. | 2 |
skip | The current values stay. New keys are written. | 0 |
overwrite | The file's values replace the current ones. | 0 |
fail | Nothing is written. | 2 |
Keys with the same value are never sent again. --force writes every key without reading the environment first; prefer --on-conflict overwrite, which reports what changed.
The JSON output
{
"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 }
}
gitisnullwhen the file is not inside a git repository.ignoredLineslists the numbers of lines in a.envfile that are notKEY=valueentries, comments or blank lines. They are skipped, and the same warning goes to stderr. Their contents are never shown: ask the user to fix those lines.
On an error the JSON is { "error": "<code>", "message": "...", "keys": [...] }. keys lists the conflicting keys for conflict, and the invalid names for invalid_keys (a name that looks like a value is counted, not shown).
| Code | Exit | Meaning |
|---|---|---|
conflict | 2 | Keys exist with another value; nothing was written |
env_not_found | 1 | The environment does not exist; add --create-env |
invalid_keys | 1 | Some key names are not letters, digits and _; nothing was written |
file_not_found, format, parse | 1 | The file is missing or cannot be read |
usage | 1 | Flags that cannot be combined, or an unknown policy |
api | 1 | The server refused the request |
A missing environment is reported as env_not_found. Add --create-env to create it, or run envshed env create first.
After the import
git.tracked: truemeans the file is committed, so its values are in the repository history. Remove the file from git and rotate those secrets.git.ignored: falsemeans the file is not in.gitignore. Add it, or delete the file.- Once
envshed run -- <command>works, the.envfile is no longer needed. Deleting it is your call; the agent should ask first. - Run
envshed scanto find any of these values in local agent histories.
What this does not protect against
- The agent runs with your login. It can do what you can do with the CLI, including commands that print values, such as
envshed secret get. The Claude Code hooks block the known ones, and other agents have no hooks. See What this does not protect against. envshed runmasks values in the command's output, but a program that transforms a value or writes it to a file gets past the mask.- Error messages from file parsing show at most a line number, never the content. Messages from the server can name keys, never values.
- The MCP server does not create projects or import files: it never handles values. Use the CLI.