pamenv CLI Guide

Install

Requires Node.js ≥ 20.19. Install globally after publish, or run via pnpm in this monorepo.

npm install -g pamenv-cli
# or
npx pamenv --help

# monorepo
pnpm --filter pamenv-cli build
pnpm pamenv --help

Login

Browser device authorization is the default: the CLI prints a user code and URL; after you approve in the browser, the token is stored in `~/.pam/config.json` (mode 0600 on POSIX). Tokens last 30 days by default (`PAM_CLI_TOKEN_EXPIRES_IN`, e.g. `21d`) and are revocable via `jti`. `pamenv logout` revokes the server token, then clears local auth and sync baselines.

pamenv login
pamenv logout

Commands

Local files default to `.env.<environment>` (e.g. `-e local` → `.env.local`). Use `--file .env` to override (relative to `-o`/cwd or absolute). Without `-e`, the first environment in the list is used. Use `pamenv init` to create a new project.

pamenv login
pamenv projects
pamenv init
pamenv init -o ./packages/app
pamenv fork <slug|id>
pamenv fork <slug|id> -y
pamenv pull <slug|id>
pamenv pull <slug|id> -e staging
pamenv pull <slug|id> -e local --file .env
pamenv pull <slug|id> -e staging -f
pamenv push <slug|id> -e staging
pamenv push <slug|id> -e local --file .env
pamenv push <slug|id> -e staging -y
pamenv push <slug|id> -e staging -f
pamenv push <slug|id> -e staging --show-values
pamenv remove <slug|id> -e local
pamenv remove <slug|id> -e local -y
pamenv logout

Init (create project)

After login, run `pamenv init` in the project directory (`-o` sets the cwd). The CLI scans package.json (name / description / homepage) and git origin; without a package it uses the repo name as the default project name. You confirm name first, then the slug derived from that name (no default if conversion is empty). When `.env` / `.env.local` / `.env.xxx` exist, multi-select environments and confirm each env name and url (url defaults to homepage when valid); `.env` and `.env.local` merge into `local`. With no env files, no environments are created. init creates empty envs only — upload with `pamenv push <slug> -e <env>`. Slugs are globally unique among non-deleted projects and reusable after soft-delete. If the slug already exists and you own it, use push instead.

pamenv login
cd your-project
pamenv init
# then upload variables (.env.local by default, or --file .env)
pamenv push <slug> -e local --file .env

Fork project

`pamenv fork <slug|id>` copies someone else's public project into a private project. Forking your own projects is not allowed. Sensitive values are cleared; env structure and non-sensitive values are kept. Confirm slug/name interactively, or pass `--slug` / `--name` / `-y`. Then fill secrets with `pamenv push <new-slug> -e <env>`.

pamenv fork <slug|id>
pamenv fork <slug|id> --slug my-app-fork --name "My App (fork)"
pamenv fork <slug|id> -y
pamenv push <new-slug> -e local

Pull / Push sync

`pull` writes remote values into the local file and preserves local comments when possible; on semantic conflicts you can overwrite or abort. `push` uses `~/.pam/sync` baselines for a three-way compare: remote-only changes ask you to pull first; both sides changed triggers a conflict prompt. `-f` only skips conflict overwrite confirms; `-y` skips ordinary confirms (missing baseline, final push, new-key sensitivity), and neither implies the other. Diff review masks values as `*****` by default; `--show-values` shows non-sensitive plaintext only. `--file` overrides the local dotenv path (e.g. `pamenv push <slug> -e local --file .env` when you only have `.env`). `pamenv remove <slug> -e <env>` deletes a remote environment (project admin required; two confirms, skip with `-y`), clears the matching sync baseline, and does not delete local `.env.*` files.

Sensitive variables

Mark sensitive keys with `# pam:sensitive` above the variable (adjacent is fine; comments may sit in between). Header and inline comments are preserved with the file.

# DB password
# pam:sensitive
API_TOKEN=xxxx # production only
NORMAL=1

Permissions and notes

Team access: owner / admin / member can `pull` and `push` (decrypted export). `pamenv remove` requires admin (including project owner). Project transfer/delete is owner_id only via Web General. Local `~/.pam/config.json`, `~/.pam/sync/...`, and written `.env.<env>` files use mode 0600 on POSIX. Rebuild the CLI after source changes before running. Legacy tokens without `jti` are rejected; run `pamenv login` again.