CLI reference

With no command: setup in a new folder, status in a linked one. Status shows the project, the token, contexts with set counts, and the run command. Without a terminal in an unlinked folder it prints next steps and exits with code 1. A clone with a committed project.json but no token on this machine gets its project named, and the way to sign in.

npx getmyenv         # setup or status
npx getmyenv status  # status only
npx getmyenv start --template <id or link>

start is the same as bare getmyenv. With --template, it adds the template's variable names and asks for each value with hidden input. Enter skips one.

Setup writes files in .getmyenv/. See what is in .getmyenv.

Commit .getmyenv/template.json. It lists the variable names, never values. In a fresh clone, npx getmyenv can start a new project from it and asks for each value. set, import, unset, restore, start --template, ls and status keep it up to date. Server tokens and GETMYENV_TOKEN never write it.

In setup, when project.json and the file both exist, you choose: sign in to that project, or a new project from the file. Values, members and tokens do not carry over. guest declares the file's names too, and lists the ones with no value.

A file that is not valid is never overwritten. The CLI says so and leaves it as is.

Commands take -c, --context <slug>. run also takes the slug as its first argument. The default is the server token's context, then project.json, then development.

Start a command with a context's variables in its environment. No SDK, no .env file.

npx getmyenv run -- npm run dev
npx getmyenv run staging -- npm start
npx getmyenv run --explain staging       # names and origins, no command

• A variable with no value in this context stops the run and prints its name. --allow-missing runs anyway. A name already set in the parent environment counts as set.
• getmyenv values replace the parent environment and the replaced names are printed. --keep-existing keeps the parent values instead.
• --explain lists each name and where its value comes from. Never values.
• run refuses context values for names that change how programs start, like NODE_OPTIONS, PATH, LD_PRELOAD, DYLD_*, GIT_*, NPM_CONFIG_*, HTTPS_PROXY and BASH_ENV. Anyone who can write the context could otherwise run code on this machine. The list is best effort, so only give write access to people you trust. --allow-unsafe-env runs anyway. set and import warn when you add one.
• Names starting with GETMYENV_ are the CLI's own settings. run never passes them from a context, even with --allow-unsafe-env. set and import refuse them.
• Status lines go to stderr. The exit code is your command's exit code.

npx getmyenv context list
npx getmyenv context create "Customer Acme" [--from development] [--use]
npx getmyenv context use customer-acme

create makes an open context. --from copies values from an open context. use saves the default in .getmyenv/project.json.

npx getmyenv set API_KEY               # prompts, input hidden
npx getmyenv set A=1 B=2 -c staging
npx getmyenv set API_KEY= DB_URL=       # declare names, no values
npx getmyenv set --missing              # asks for every name with no value
npx getmyenv set KEY=value --expires 2026-12-31
npx getmyenv unset KEY [-c staging]
npx getmyenv unset KEY --all            # every context
printf %s "$VALUE" | npx getmyenv set KEY --stdin

Open contexts only. --stdin reads one value from a pipe, so it stays out of the command line.

--missing asks, with hidden input, for every variable that has no value in the context. Leave one empty to skip it. Agents declare the names with set KEY1= KEY2=, then the human runs set --missing in a terminal.

set KEY= on a name that already has a value says so and changes nothing. An empty value does not clear a value. Use unset.

Use uppercase letters, numbers and underscores, like API_KEY. Start with a letter or underscore. set and unset refuse other names and suggest one: database_url gets "Did you mean DATABASE_URL?"

A grid of names by context: set, missing, or expired. Read-only contexts are marked. Never values.

npx getmyenv ls

Encrypt a .env file and upload it. With no file, it reads the env files in this folder. .env and .env.local go to the default context. .env.<slug> goes to that context, created as open after you confirm. Read-only contexts are skipped. The file is left as is. UTF-8 and UTF-16 files both work. A name that appears twice gets a warning, and the last value is used.

npx getmyenv import
npx getmyenv import .env.staging
npx getmyenv import .env -c customer-acme --dry-run
npx getmyenv import --prune   # also unset names not in the file
npx getmyenv import --yes     # do not ask

Write a context to a plaintext .env for tools that need a file. The file is added to .gitignore, and on macOS and Linux only you can read it. It asks before changing or removing values in an existing file.

A Read-only context exports with its server token, under the same rules as run: an allowlisted IP, and a trusted or approved machine.

npx getmyenv export               # writes .env
npx getmyenv export -o .env.local -c staging
npx getmyenv export --yes          # do not ask
npx getmyenv export --stdout
npx getmyenv export -c production -o /srv/app/.env --yes   # server token

Copy a context to Vercel or Netlify. The CLI decrypts locally and pushes with your platform token from VERCEL_TOKEN or NETLIFY_AUTH_TOKEN. It prints names and types only, then asks. Future changes in getmyenv are not pushed automatically. Setup, types and prune rules: /docs/deploy-platforms.

npx getmyenv push vercel -c production --dry-run
npx getmyenv push vercel -c production
npx getmyenv push netlify -c production --prune

Create a guest project without an account. The same as Start without an account in setup, with no prompts. Writes .getmyenv/claim.json for a human to claim later. At a terminal, guest prints the claim code and guest passphrase once. Run by an agent or a script, it prints neither, and claim.json is the only copy. If the folder is lost before claim, the project cannot be claimed. A clone with .getmyenv/template.json can start a new project with the same names.

npx getmyenv guest --name my-app
# Commit .getmyenv/project.json and .getmyenv/template.json
# token.json and claim.json stay local (gitignored)

Guest projects have Development only. Claiming adds Production (Read-only). A guest project stays active while the CLI uses it. After 30 days without use, or 180 days after it was created, values can't change. For 30 more days, run still works and it can still be claimed. Unclaimed projects may be deleted after that. Creation is limited per IP. While guest, the CLI reads the passphrase from claim.json, so there is no Vault password prompt.

Keep claim.json private. Do not print it, paste it in chat, or add it to git. The human runs npx getmyenv claim in the same folder, and claim reads it.

Take ownership of a guest project. Opens the browser with the claim code from claim.json, after # in the link, so it never reaches the server or proxy logs. The page keeps it through sign-in, then asks for the code the terminal prints. A link alone cannot claim the project. Without claim.json, it asks for the claim code and guest passphrase. Then it seals the context keys to your account. If your account has no Vault password yet, it asks for one, then shows your recovery code once and asks you to type it back.

npx getmyenv claim

After claim, values open with the human's Vault password. The human runs npx getmyenv run -- <start command> once in a terminal to unlock. Then run works without a prompt for 8 hours.

backup writes an encrypted .getmyenv-backup file with the open contexts. restore puts one back into this folder's project with a folder token. It encrypts the values again with the project's current keys. A backup opens with the Vault password or the recovery code in effect when it was made. A newer Vault password or recovery code does not open it. Backups with Read-only contexts are made and restored in the dashboard. The default file name is <project>.getmyenv-backup.

npx getmyenv backup -o project.getmyenv-backup
npx getmyenv restore project.getmyenv-backup --dry-run   # check, change nothing
npx getmyenv restore project.getmyenv-backup [--yes]

Forget every unlocked context key on this machine, for all projects. The next run asks for the Vault password.

npx getmyenv lock

Revoke this folder's token and remove token.json and project.json, and this project's unlocked keys in the OS keychain. claim.json and template.json stay. The project and its values stay on the server. In a guest project the guest token is kept, so claim still works with claim.json. Without a token on this machine, a committed project.json stays.

When the server cannot be reached, nothing is removed. --local removes the local files without revoking the token. The token then keeps working on the server until it expires or its project ends.

npx getmyenv unlink
npx getmyenv unlink --yes     # do not ask
npx getmyenv unlink --local   # local files only, the token is not revoked

The CLI says why, then what to do. A folder token says to run npx getmyenv unlink, then npx getmyenv. A server token says to create a new one in Project settings, Tokens. An expired token gives its date. A token stops working when:

• The owner or a super admin deleted the project.
• An expired guest project was deleted.
• Someone claimed the guest project. Its guest tokens stop working.
• The owner removed you from the project.
• You left the project.
• You gave the project to a new owner and did not stay as a member.
• The owner reset the Read-only context the server token reads.
• The context the server token reads is no longer Read-only.
• The context the server token reads was deleted.
• The token was revoked in the dashboard.
• The account the token belongs to was deleted.

The server keeps the reason for 1 year, the longest a token can last. After that, the CLI says the token no longer works, without a reason.

Built from the same list the CLI uses, so it matches npx getmyenv --help. npx getmyenv help <command> shows one command.

npx getmyenv start
  Set up this folder (same as bare npx getmyenv). Status when already linked.
    --template <id>  Add a template's variables and ask for their values (id or link)

npx getmyenv run [context] [options] -- <command...>
  Run a command with a context's variables in its environment
    -c, --context <slug>  Context to use (default: the server token's context, then project.json, then development)
    --explain             List each variable and where its value comes from (names only)
    --keep-existing       Keep variables already set in the parent environment
    --allow-missing       Run even when some variables have no value in this context
    --allow-unsafe-env    Run even when the context sets NODE_OPTIONS, PATH, LD_PRELOAD, GIT_*, *_PROXY or similar. The list is best effort

npx getmyenv status
  Show project, token, contexts and the run command

npx getmyenv context list
  List contexts (* marks this folder's default)

npx getmyenv context create <name>
  Create an open context, e.g. context create "Customer Acme"
    --from <slug>  Copy values from an open context
    --use          Make it this folder's default

npx getmyenv context use <slug>
  Set this folder's default context (saved in project.json)

npx getmyenv set [pairs...]
  Set values: set KEY=VALUE, set KEY to be prompted, or set --missing
    -c, --context <slug>  Context to use (default: the server token's context, then project.json, then development)
    --expires <date>      Expiry date, e.g. 2026-12-31, or never
    --stdin               Read the value of one KEY from stdin (keeps it out of argv)
    --missing             Ask (hidden) for every variable with no value in the context

npx getmyenv unset <names...>
  Remove values from a context
    -c, --context <slug>  Context to use (default: the server token's context, then project.json, then development)
    --all                 Delete the variable from every context

npx getmyenv ls
  Variable names by context with status (never values)
    -c, --context <slug>  Context to use (default: the server token's context, then project.json, then development)

npx getmyenv import [file]
  Encrypt a .env file and upload it (.env.<slug> goes to that context)
    -c, --context <slug>  Context to use (default: the server token's context, then project.json, then development)
    --prune               Unset values in the context that are not in the file
    --dry-run             Show what would change without uploading
    --yes                 Do not ask for confirmation

npx getmyenv export
  Write a context to a plaintext .env file, for tools that need one
    -c, --context <slug>  Context to use (default: the server token's context, then project.json, then development)
    -o, --output <file>   Output file (default: .env)
    --stdout              Write to stdout instead of a file
    --yes                 Change an existing file without asking

npx getmyenv push <provider>
  Copy a context to Vercel or Netlify with your platform token (VERCEL_TOKEN, NETLIFY_AUTH_TOKEN)
    -c, --context <slug>  Context to use (default: the server token's context, then project.json, then development)
    --project <id>        Vercel project id or name (default: .vercel/project.json)
    --team <id>           Vercel team id (default: .vercel/project.json)
    --site <id>           Netlify site id (default: .netlify/state.json)
    --target <env>        Vercel: production, preview or development. Netlify: production, deploy-preview, branch-deploy or dev (default: production)
    --prune               Also remove variables from this target that are not in the context
    --dry-run             Show what would change (names and types only) without writing
    --yes                 Do not ask for confirmation

npx getmyenv guest
  Create a guest project without an account. It stays active while you use it, up to 180 days. Claim it to keep it.
    --name <name>  Project name (default: folder name)

npx getmyenv claim
  Claim a guest project (reads .getmyenv/claim.json, or asks for the claim code)

npx getmyenv backup
  Write an encrypted backup of open contexts
    -o, --output <file>  Output file (default: <project>.getmyenv-backup)

npx getmyenv restore <file>
  Restore a backup into this folder's project (open contexts with the same slug)
    --dry-run  Check the backup and show what would be restored
    --yes      Do not ask for confirmation

npx getmyenv lock
  Forget every unlocked context key on this machine (OS keychain)

npx getmyenv unlink
  Revoke this folder's token and remove local .getmyenv files
    --yes    Do not ask for confirmation
    --local  Remove the local files without revoking the token (it keeps working until it expires)

npx getmyenv help [command]
  Show help for a command (same as <command> --help)

Every command
    -V, --version    Print the version
    --api-url <url>  API base URL
    -h, --help       Show help

GETMYENV_TOKEN          Token for CI and servers (instead of .getmyenv/token.json). A server token holds its context key.
GETMYENV_API_URL        API base URL (https, or http://localhost)
GETMYENV_CONFIG_DIR     Machine identity and cache dir (default ~/.config/getmyenv)
GETMYENV_SKIP_UPDATE    Set to 1 to skip the update notice
GETMYENV_KEYCHAIN       Set to 0 to always ask for the Vault password
GETMYENV_MACHINE_LABEL  Name shown for this machine in access requests
GETMYENV_PUSH_API_URL   Vercel or Netlify API base URL, for tests (https, or http://localhost)