Skip to main content

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​

  1. Install the CLI: npm install -g envshed.
  2. 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.
  3. For Claude Code, run envshed agent install. It adds hooks that stop the agent from reading .env files and a skill with these steps. See Agent hooks.

What the agent runs​

Replace <org>, <project> and the file and environment names with yours.

terminal
# 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​

output
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-conflictWhat happens to conflicting keysExit code
not set, no terminalNothing is written. The key names are listed.2
skipThe current values stay. New keys are written.0
overwriteThe file's values replace the current ones.0
failNothing 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​

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 is null when the file is not inside a git repository.
  • ignoredLines lists the numbers of lines in a .env file that are not KEY=value entries, 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).

CodeExitMeaning
conflict2Keys exist with another value; nothing was written
env_not_found1The environment does not exist; add --create-env
invalid_keys1Some key names are not letters, digits and _; nothing was written
file_not_found, format, parse1The file is missing or cannot be read
usage1Flags that cannot be combined, or an unknown policy
api1The 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: true means the file is committed, so its values are in the repository history. Remove the file from git and rotate those secrets.
  • git.ignored: false means the file is not in .gitignore. Add it, or delete the file.
  • Once envshed run -- <command> works, the .env file is no longer needed. Deleting it is your call; the agent should ask first.
  • Run envshed scan to 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 run masks 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.