CLI reference

Every envhq command, its options, and the config files it reads and writes.

Install

npm install -g envhq
# or run without installing
npx envhq <command>

Authentication

Command	Description
`envhq login`	Authenticate via your browser (opens a loopback PKCE flow). Add `--token <token>` to use a personal access token instead (headless/CI), and `--url <url>` to target a non-default server.
`envhq logout`	Remove stored credentials from the OS keychain.
`envhq whoami`	Show the authenticated user.
`envhq status`	Show login and link state for the current folder, plus the target server URL.

Browser logins mint a token that expires after 7 days; expired sessions trigger the browser flow again automatically on the next push/pull (this auto-relogin is skipped for tokens sourced from --token or ENVHQ_TOKEN — those just report the error with guidance to rotate).

Projects

Command	Description
`envhq orgs`	List the organizations you belong to (your personal org plus any teams you've been invited to).
`envhq projects`	List your projects. `--org <name>` lists a specific org's projects instead of your personal org.
`envhq init [name]`	Bootstrap the current folder: create a project (name defaults to the folder name), create environment(s), and link the folder. Idempotent — no-ops if already linked. `-e, --env <names>` comma-separated environments (default `dev`). `--org <name>` creates it in a team org instead of your personal org.
`projects create <name>`	Create a new project (and its environment(s)) and link this folder to it. `-e, --env <names>` (default `dev`), `--org <name>`, `--no-link` to skip linking.
`envhq link`	Link this folder to an existing project, mapping every environment to a local file. `-p, --project <name>` to skip the picker, `--org <name>` to pick from a team org instead of your personal org.

--org matches an org by name, case-insensitively. Omitting it always defaults to your personal org — existing scripts and CI behave exactly as before.

Environments

Command	Description
`env create <name>`	Create an environment in a project. `--from <env>` clones another environment's variables server-side. `-p, --project <name>` targets a project other than the linked one. `--link` links this folder to the new environment.
`env list`	List environments in a project (shows the linked file mapping when applicable). `-p, --project <name>`.
`env map <env> <file>`	Change which local file an environment maps to.

Sync

Command	Description
`envhq push [env]`	Three-way sync a local file to the remote: adds new keys, updates changed ones, and propagates deletions (a key you removed locally, and that hasn't changed remotely, is deleted remotely too) — computed against a local sync record written by the last `push`/`pull`, not a blind overwrite. `[env]` defaults to the link's default environment. `-f, --file <path>` overrides the mapped file. `--all` pushes every linked environment (mutually exclusive with an explicit env/file). `--yes` skips the prod and deletion confirmations. `-m, --message <msg>` tags the resulting version with a commit message.
`envhq pull [env]`	Write remote variables to a local file. Cloud wins for every key it already knows about; a local key you added since the last sync (not yet on the remote) is merged forward instead of discarded. The previous file contents are always backed up to `<file>.bak` first. Same `[env]` / `-f, --file` / `--all` / `--yes` semantics as `push`, plus `--force` to overwrite without the confirmation prompt.
`envhq diff [env]`	Preview exactly what `push` would add, update, or delete, without applying it. Same `[env]` / `-f, --file` / `--all` as `push`.

push/pull/rollback targeting an environment named prod or production ask for confirmation unless you pass --yes; a pushthat would delete remote keys asks separately. Deleting an entire environment or project (from the web app) is still permanent — there's no undo for that. See Limitations & FAQ.

Version history

Command	Description
`envhq history [env]`	List every version of an environment: version number, timestamp, who committed it, and its message. `--all` shows history for every linked environment.
`envhq rollback <version> [env]`	Restore an environment to a previous version's exact set of keys and values. This creates a new version rather than rewriting history (like `git revert`, not `git reset`) — nothing is lost, and you can always roll back the rollback. `-m, --message <msg>` sets the new version's commit message; `--yes` skips confirmation.

Every commit — a CLI push, a web edit, an import, or a rollback — creates a new version. Concurrent pushes are conflict-checked: if the environment moved since you last read it, push/rollback fails with the conflicting keys and their server-side values instead of silently overwriting them; run pull and try again.

Config files

~/.envhq/config.json — global config: the server url (your token lives in the OS keychain, never in this file).
./.envhq/config.json — per-folder link: project id/name, the environments → file map, and the default environment. Gitignored automatically.

Older .envsync/ config (or the legacy single-env .envsync.json) from before the project's rebrand from envsync to EnvHQ is auto-migrated the first time you run a command in a folder that has it, including any OS-keychain session stored under the old service name.

Environment variables

Variable	Purpose
`ENVHQ_URL`	Override the server URL for a single command or session (also settable per-command with `--url`/`-u` on `login`).
`ENVHQ_TOKEN`	Use a personal access token from the environment instead of the OS keychain — the standard way to authenticate in CI.