# CLI

The CLI is published as `envpass-cli` on npm and PyPI. Both packages install a command named `envpass` and behave the same way, and they share login credentials.

```bash
bunx envpass-cli <command>    # Bun
npx envpass-cli <command>     # Node.js 20+
uvx envpass-cli <command>     # Python 3.9+ with uv
pipx run envpass-cli <command>
```

Install globally to get the shorter `envpass` command:

```bash
npm install -g envpass-cli    # or: pip install envpass-cli
envpass pull
```

## Commands

### login

Signs in through your browser using the OAuth device flow and saves a token to `~/.config/envpass/credentials.json` (file mode 600).

```bash
envpass login
envpass login --no-browser    # over SSH: prints the link instead of opening it
```

### logout

Revokes the CLI session on the server and removes the saved token.

### whoami

Shows the user or service token the CLI is using.

### link

Saves default scope to `.envpass.json` in the current directory. The file contains slugs only and is safe to commit.

```bash
envpass link -w acme -p shop -e dev
```

### pull

Writes the resolved values for one environment to a file.

```bash
envpass pull                     # .env, using .envpass.json
envpass pull -e prod -o .env.production
envpass pull -e prod -o -        # stdout
envpass pull -e prod -f json     # json or shell exports
```

Files are written with mode 600.

### run

Runs a command with the values injected as environment variables. Values that appear in the command's output are replaced with `***`.

```bash
envpass run -e dev -- bun dev
envpass run -e staging -- python worker.py
envpass run --no-mask -e dev -- printenv
```

The exit code of the command is passed through.

## Webhooks and syncs

These commands manage workspace settings, so they need a user login from `envpass login`. A service token is refused with a message saying so; unset `ENVPASS_TOKEN` if it holds one. The workspace and project come from `-w` and `-p`, `ENVPASS_WORKSPACE` and `ENVPASS_PROJECT`, or the nearest `.envpass.json`, like every other command. When your login has a single workspace, `-w` can be left out.

`webhooks list`, `webhooks deliveries` and `syncs list` print a plain table. Add `--json` to print the raw API response instead.

### webhooks list

Lists the workspace's webhooks: id, URL, events, environments (or `all`), on or off, and the status of the last delivery.

```bash
envpass webhooks list
envpass webhooks list --json | jq '.[].url'
```

### webhooks add

Registers a webhook and prints its signing secret. The secret is shown only once: store it where your receiver can read it and use it to verify the `envpass-signature` header.

```bash
envpass webhooks add --url https://example.com/hooks/envpass
envpass webhooks add --url https://hooks.slack.com/services/... --event secrets.changed -e prod
envpass webhooks add --url https://example.com/hooks/envpass \
  --event sync.failed --event sync.succeeded -p shop --description "Deploy bot"
```

| Option | Description |
|---|---|
| `--url` | The endpoint envpass POSTs to. Required. |
| `--event` | `secrets.changed`, `sync.succeeded` or `sync.failed`. Repeat for more. Default `secrets.changed` and `sync.failed`. |
| `-e, --env` | Only fire for these environment slugs. Repeat for more. Default all. |
| `-p, --project` | Only fire for these project slugs. Repeat for more. Default all. |
| `-f, --format` | `json` or `slack`. Default `slack` for `hooks.slack.com` URLs, `json` otherwise. |
| `--description` | A note to tell webhooks apart. |

In `webhooks add`, `--url` is the endpoint. Point the CLI at a self-hosted server with `ENVPASS_URL`.

### webhooks remove

Deletes a webhook.

```bash
envpass webhooks remove 0193b3c2-6a8e-7c1f-9b0e-2f9d2a4c1e77
```

### webhooks test

Sends a test event and prints the response status and time. Exits with 1 when the delivery fails, so it works as a check in scripts.

```bash
envpass webhooks test 0193b3c2-6a8e-7c1f-9b0e-2f9d2a4c1e77
# Delivered: HTTP 200 in 143ms
```

### webhooks deliveries

Shows recent deliveries for a webhook, newest first: event, status, response code, attempts, duration, time and error.

```bash
envpass webhooks deliveries 0193b3c2-6a8e-7c1f-9b0e-2f9d2a4c1e77 --limit 10
```

`--limit` takes 1 to 100. The default is 25.

### syncs list

Lists the project's syncs: id, destination, environment, status (`paused` when turned off), last sync time and last error.

```bash
envpass syncs list
envpass syncs list -p shop --json
```

### syncs run, pause, resume

`run` queues a sync to push now. `pause` stops a sync from running on secret changes, and `resume` turns it back on. A paused sync can't be run until it is resumed.

```bash
envpass syncs run 0193b3c2-6a8e-7c1f-9b0e-2f9d2a4c1e77
envpass syncs pause 0193b3c2-6a8e-7c1f-9b0e-2f9d2a4c1e77 -p shop
envpass syncs resume 0193b3c2-6a8e-7c1f-9b0e-2f9d2a4c1e77 -p shop
```

## Options

| Option | Environment variable | Description |
|---|---|---|
| `-w, --workspace` | `ENVPASS_WORKSPACE` | Workspace slug. Not needed with a service token. |
| `-p, --project` | `ENVPASS_PROJECT` | Project slug. Not needed with a service token. |
| `-e, --env` | `ENVPASS_ENV` | Environment slug, for example `dev` or `prod`. |
| `-o, --out` | | `pull` output file, `-` for stdout. Default `.env`. |
| `-f, --format` | | `pull` format: `dotenv`, `shell` or `json`. |
| `--json` | | `webhooks list`, `webhooks deliveries` and `syncs list`: print raw JSON. |
| `--limit` | | `webhooks deliveries`: how many to show, 1 to 100. Default 25. |
| `--url` | `ENVPASS_URL` | Server URL. Default `https://envpass.dev`. |
| | `ENVPASS_TOKEN` | A service token (`ep_live_...`) or CLI session token. |

Scope is resolved from flags first, then environment variables, then the nearest `.envpass.json`.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (not signed in, forbidden, not found, invalid input), or a failed `webhooks test` |
| 127 | `run` could not start the command |
| other | `run` passes through the command's exit code |