Pular para o conteúdo principal
informação
Esta página ainda não foi traduzida. Você está lendo a versão em English.

envshed init

Connect local application folders to Envshed projects. Init reuses a valid login or opens the existing device authorization flow, detects applications, prepares a plan and asks before creating projects or changing configuration.

terminal
npx envshed@latest init
npx envshed@latest init -o my-team -p my-app -e development

Run inside the application folder or the common parent of several applications. Node.js and npm are required for npx; the package is downloaded to the npm cache, not installed globally. An installed CLI can use envshed init directly.

The setup screen​

In a terminal, envshed init without plan flags opens a step-by-step screen. Each step is one table or list, with the steps in a line at the top and your choices kept as you go back and forth:

StepWhat you decide
Project (single folder) or Organization (monorepo)Which organization. A single folder then asks which project, in the same step; a monorepo asks per app in the next step
AppsMonorepo only: one project per app, or one project for the whole repository. The repository root is a row of the table
FilesThe environment each .env file goes to
Default environmentThe environment envshed run and envshed pull use when you don't pass -e
ConfirmOne summary of what will be written

Nothing is created or written before Confirm. ← goes back (or closes a list), → goes on, enter chooses, and Ctrl+C leaves with nothing created.

Files​

The Files step is a table with one row per .env file: its name, how many secrets it holds and the environment it goes to. Press enter on a row to change its environment, create a new one or choose Don't import. Only names and counts are shown, never values.

output
File Secrets Environment
❯ .env 16 development merged with .env.development
.env.ci 7 not imported
.env.development 14 development 2 secrets replaced by .env
.env.local 9 not imported
.env.production 15 production
.env.staging 15 staging
.env.test 8 test (new)

[ Continue → ]

1 template not imported (.env.example)
1 ignored file (.env.backup) i to show

Example with sample data.

  • A file whose name says the environment is suggested for it (.env.production goes to production). .env goes to development.
  • .env.local, .env.ci, .env.docker and other names are not imported until you choose an environment for them.
  • Templates (.env.example and similar) are never read. Ignored files are old copies such as .env.old, .env.bak and .env.backup: they are hidden and not imported. Press i to list them.
  • When two files go to the same environment, the note next to each one says what happens. If they disagree on a secret, init lists the secret names in yellow and Continue is blocked until you choose whose values win, another environment, or Don't import.

Default environment​

This step appears when a folder could use more than one environment. The one suggested is already selected: press enter to accept it. In a monorepo, a table with one row per folder lets you set each one. When every folder has a single candidate, init skips the step and marks it (skipped) in the line of steps.

Confirm​

The summary has one line of totals, then each folder with its project and files. Each file shows how many secrets are new, replaced, unchanged or the same as another file. It ends with the default environment and the file that will be written (.envshed.json). No .env file is changed or deleted.

If importing would replace a secret already saved in Envshed, the summary lists the secret names and the button becomes Replace and confirm. enter does not confirm it: press y.

After the setup​

Init shows how it went and a few hints, with no more questions:

output
✔ Done in 3 s. 66 secrets imported into 5 environments of acme/shop-web

Run the app envshed run -- npm run dev
Make it the default put "envshed run -- npm run dev" in your dev script
Other environment once envshed run -e <name> -- npm run dev
Rules for coding agents envshed agent rules

Example with sample data.

  • If an imported file is tracked by git, init warns in red: its values are already in the repository history, so remove it with git rm --cached and rotate those secrets.
  • If an imported file is not in .gitignore, init lists it. It does not change .gitignore.
  • If nothing was imported and the default environment is empty, init asks once whether to add the first secret, typed in the terminal with the value hidden.
  • Init does not delete or edit your .env files, does not wrap your dev script and does not write the agent rule. For those, use --wrap-script and --agent-rules, or the commands in the hints.

When the screen does not open​

These cases run the plan flow described in the rest of this page, with its prompts, plan and guide:

  • no terminal, CI, --yes, TERM=dumb, or a terminal smaller than 40 columns by 12 rows;
  • agent mode (ENVSHED_AGENT_MODE=1, or an agent session);
  • any plan flag: --org, --project, --env, --workspace, --all, --layout, --personal, --import, --no-import, --import-map or --create-envs.

--no-guide, --wrap-script, --agent-rules, --no-agent-rules and --api-url work with the screen too. To use the previous flow in a terminal, pass a plan flag such as --org.

Options​

OptionDescription
-o, --org <slug>Use an existing organization/workspace
-p, --project <slug>Reuse this project for the selected application(s); missing projects require interactive creation review
-e, --env <slug>Shared default environment to save; missing environments are included in the creation plan
-w, --workspace <path>Select one application directory explicitly, relative to the setup root
--allSelect all suggested runnable applications; libraries and root orchestrators remain optional
-y, --yesAccept the printed setup plan without prompts; may create projects/environments
--no-guideSave validated configuration without the interactive run guide. Does not affect the env file import, see --no-import
--personalSave the connection on this machine only, outside the project. Nothing is created or changed in the repository. See Only for me
--import [file=env]Alone: import the env files whose name says the environment (.env, .env.local, .env.production...) without asking. As file=env, repeatable: that file into that environment, e.g. --import .env=development --import .env.production=production
--layout <repo|apps>When the folder holds more than one app or env file location: repo makes one project for the whole repository, apps one project per app
--no-importDo not look for env files
--import-map <pairs>Map files to environments without prompts, e.g. .env.local=development,.env.production=production. Files not listed are skipped
--create-envsCreate the environments named by --import-map (or suggested by file names) when they do not exist. Needs permission to create environments
--api-url <url>Explicitly select and persist a personal API destination outside the repository. Must be HTTPS (plain HTTP only for localhost). Switching to a different destination discards the saved token, so you sign in again there; a token is never sent to another API

Interactive input is required for unresolved choices. Noninteractive runs require authentication and explicit answers; use --yes only when the printed plan's possible resource creation is intended. Init never falls back to another credential when ENVSHED_TOKEN is invalid. A 403 is an access/plan failure, not a reason to reopen login.

One application​

Init reuses existing mappings and development environments when available. It saves shared metadata in .envshed.json:

json
{
"org": "my-team",
"project": "my-app",
"defaultEnv": "development"
}

This file contains no tokens or secret values. Personal environment selections remain in ~/.envshed/contexts.json and are not overwritten by init. The first guided run explicitly targets the environment reviewed in setup; later normal runs use the context precedence.

When the folder already has env files, init offers to import them right after the connection is saved. See Import existing env files. New applications can add values in the dashboard. No env file is created or synchronized implicitly.

In the plan flow (see When the screen does not open), when a runnable command is known, init offers to execute it through the existing run path. Starting a process does not prove the application is ready: the guide asks for your confirmation separately. Repeat init to reopen the guide. The setup screen has no guide: it ends with hints.

Import existing env files​

In the setup screen, the Files table does this. The rest of this section describes the plan flow, where init looks for env files in the folder it runs in and in each connected app folder, and lists them all in one multi select:

output
Ignored, as templates: .env.example
? Which .env files should go into Envshed? Space selects, Enter continues. Only names and key counts are shown.
❯◉ .env → development (2 keys)
◯ .env.prod-bkp → you choose the environment (1 key)
◉ .env.production → production (1 key)
◉ demos/web/.env.local → development (1 key)

Only file names and key counts are shown, never values.

Which files. .env, .env.* and *.env in the folder init runs in and in each connected app folder (in a monorepo, each selected package). Templates (.env.example, .env.sample, .env.template, also as .env.local.example) are listed as ignored and never read. Init also skips the dotenvx companions .env.vault and .env.keys, symlinks, files over 1 MB, empty files and any output file configured for envshed pull in .envshed.json. Subfolders of those folders are not searched.

The top folder. When the folder init runs in has env files and is not an app itself, its files are not left out: with one project for the repository they go to it; with one project per app they go to the only app's project, or to the one you pick.

Where each file goes. A file whose name says the environment comes selected with it. Other names, like .env.prod-bkp or .env.old, come unselected; select one and init asks for its environment, with Create new environment (name prefilled from the file name). Then init lists each file and its environment: keep it, or change any line (Back reopens the previous file). The suggested environment comes from the file name:

FileSuggested environment
.env.production, .env.prod, .env.vercel.productionproduction (or an existing prod/prd/live)
.env.staging, .env.previewstaging (or an existing stage/stg/preview/uat)
.env.testtest
.env, .env.development, .env.devthe default environment chosen in init
.env.local, .env.*.localunselected: they usually hold values for one computer only, and importing them makes them the team's values. Picked, they go to the default environment
anything else, e.g. .env.qaunselected; the file suffix (qa) is offered as a new environment

Two files may go to the same environment. Files are applied in alphabetical order, so .env.local overrides .env, and every key that differs between them is listed by name.

Plan. Before anything is written, init shows the whole setup in one plan: the organization, each project (new or existing), the default environment, the configuration file it writes, and, per environment, how many keys are new, how many would change and how many stay the same, with the files that feed it. One confirmation applies everything; answering no writes nothing. The import uses the same write path as envshed import, one environment at a time. New environments are created through the API with the same permission checks as envshed envs create.

After the import. Init prints the next step (envshed run -- <dev command>) and then:

  • warns when an imported file is tracked by git: its values are already in the repository history, so remove it with git rm --cached and rotate those secrets;
  • offers to add files that git does not ignore to .gitignore. For a personal connection it uses .git/info/exclude instead, so no file of the repository changes. Default: no;
  • offers to delete the imported files now that Envshed holds the values. Default: no.

Existing loaders (for example Next.js reading .env.local) may still read files you keep and override injected values; review them before relying only on Envshed.

Scripts and CI​

Without a TTY, init never imports unless asked, and --yes alone imports nothing:

terminal
# Map files explicitly; files not listed are skipped
envshed init -o my-team -p my-app -e development --yes \
--import .env=development --import .env.production=production

# Only the files whose name says the environment; others (.env.prod-bkp) are skipped and named.
# Files of the top folder, when it is not an app, go in only when named (--import .env=development).
envshed init -o my-team -p my-app -e development --yes --import

# One project for the repository, even with an app in a subfolder
envshed init -o my-team -p my-app -e development --yes --layout repo --import .env=development
  • In a monorepo, a file name present in several packages must be written with its path, e.g. --import apps/web/.env.local=development.
  • An explicit file=env fails for a file it cannot find, and for an environment that does not exist unless --create-envs is passed or the project is created by this run.
  • Without a TTY, an import that would change existing values stops unless --yes is passed.
  • --no-import cannot be combined with --import file=env, --import-map or --create-envs.
  • --import-map .env=development,.env.production=production still works and is the same as repeating --import.
  • Without --layout, a folder with env files and one app in a subfolder gets one project for the repository; with several apps, pass --all or --workspace as before.

Only for me​

In the plan flow, before writing anything, init asks who the connection is for. The setup screen does not ask: it writes .envshed.json for the team, and a personal connection that already exists stays personal (the Confirm step shows where it writes). To choose, use --personal, which runs the plan flow:

  • The team (default): creates .envshed.json in the project, to commit, as described above.
  • Only me: saves the same connection on this machine, outside the project. Nothing in the repository is created or changed, so nobody else sees that you use Envshed. --personal picks this without asking.
terminal
npx envshed@latest init --personal

The personal connection is stored in ~/.envshed/connections/<id>/.envshed.json (folder 0700, file 0600), where <id> is a hash of the real path of the checkout root (the folder with .git). It has exactly the same content as a project .envshed.json, monorepo workspaces included, and every command uses it the same way. From any folder of that checkout, run commands without -o -p -e:

terminal
npx envshed@latest run -- npm run dev
  • It needs a git checkout, and it applies to that checkout only: another clone or worktree, or the same folder after being moved or renamed, is not connected. Run init --personal there again.
  • If the repository gets a .envshed.json later (for example when the team adopts Envshed), that file is used and the personal connection is ignored. To share yours with the team, run init again and choose "The team", then delete the personal folder.
  • Commands that change the connection (workspace add, workspace remove, changing or renaming the default environment) save to the personal file. No command creates .envshed.json in the repository for a personal connection.
  • The optional script integration below is not offered, because it would change package.json.
  • To remove it, delete its folder under ~/.envshed/connections/.

Multiple applications​

Declared monorepos and common parent folders containing independent applications use the same command:

terminal
npx envshed@latest init -o my-team

In the setup screen, the Apps step shows each app, the repository root and the project each one connects to, and a line switches between one project per app and one project for the whole repository. Suggested names come from each package.json. With one project for everything, apps that have .env files of their own usually conflict with the root's files, and the screen says so. In the plan flow, when the folder holds more than one app, or env files at the top and an app in a subfolder, init first asks: one project for the whole repository, or one project per app. Per app, select one or several detected applications. For each, reuse a remote project or name a new one and choose an environment. Review the consolidated plan (paths, targets, create/reuse actions and configuration files) before applying it. Project creation and environment creation remain subject to server permissions and plan limits. A remote project for the root is not required.

Discovery is read-only: package.json scripts, Python manifests, go.mod and Cargo.toml identify candidates. It traverses at most four directory levels and 500 directories (it says so only when it stops at 500), skips dependencies, build outputs, hidden directories and directory symlinks, and never executes project code. Libraries are selectable but not automatically turned into remote projects. Use --workspace <path> for a missed application; external symlinks are refused. Automatic command suggestions cover recognized Node scripts and simple Go/Rust entry points; Python/custom applications use their own command with run.

Monorepo mappings share a root .envshed.json without replacing existing root projects or unselected mappings. Independent repositories use application-local configuration rather than adding a common ancestor config. The plan names every file that will be written. Each application keeps its own environment and secrets; configuring several does not start them all in one process.

For an intentional noninteractive setup of all suggested apps:

terminal
envshed init --all -o my-team -e development --yes --no-guide

New project names are suggested from local application names in this mode. Collisions between new project plans are rejected. Pass -p only to intentionally reuse that same existing remote project for the selected applications.

Retrying and cancellation​

No project/environment is created before plan confirmation. Completed application mappings are saved incrementally and atomically. If setup stops, it reports partial completion; a remote resource may exist even if its response was lost. Rerunning init re-lists projects/environments and reuses those resources. There is no distributed transaction and no automatic deletion of successful resources. Concurrent local edits are detected and preserved.

An explicit API destination has its own confirmation and is saved as a personal setting. A reviewed configuration update removes a legacy project API override when necessary; implicit repository remote redirects remain ignored. Changing the destination does not copy credentials into the project.

Optional script integration​

For recognized Node scripts, the plan flow previews an optional integration (the setup screen only does it with --wrap-script): preserve dev as dev:local and replace dev with a pinned npx envshed@<version> run -- <package-manager> run dev:local. It keeps other scripts unchanged, refuses a collision with an existing :local name and does not wrap an existing envshed script again. Applying it is a separate explicit choice. The wrapper obtains the released CLI version on demand, avoiding a global dependency; testing an unpublished build should use the local CLI directly until that version is released.

Recovery​

  • Missing/expired saved login: device authorization, then resume.
  • Invalid ENVSHED_TOKEN: update/unset it and authenticate explicitly.
  • Access or plan refusal: select an accessible target or ask an administrator/owner.
  • Invalid JSON: repair the named file; init preserves it.
  • Network failure: retry init; inspect the printed partial progress.
  • Application failure: configuration remains saved; inspect application output and retry.