# Use secrets from the terminal

Install the CLI with `npm install -g @mocco/cli`. Use `mocco secrets run` to give one command the values you can read, without writing a plaintext file.

## Sign in and link a project

```sh
mocco login
mocco link --workspace <workspace-uuid> --project <project-uuid> --env development --path /
mocco secrets run -- yarn dev
```

Sign-in opens a browser on the same computer. `mocco login --no-browser` prints the authorization URL instead. The callback listens only on `127.0.0.1` and sign-in expires after five minutes. Headless machines use an API key.

`mocco link` prompts for missing values in a terminal; pass all four flags in scripts. Copy the workspace and project UUIDs from their console URLs. The generated `.mocco.json` contains IDs and defaults only and can be committed. The CLI searches upward from your current directory and stops at the Git repository root.

Your account has the same access as in the console. A member who can describe production secrets but cannot reveal them cannot read them through the CLI either. `mocco whoami` prints your verified account ID. It checks the token signature, issuer, secrets audience, scope and expiration locally; it does not promise immediate revocation of an already issued access token.

Credentials are stored separately for each API URL in `$XDG_CONFIG_HOME/mocco/credentials.json`, or `~/.config/mocco/credentials.json` when XDG is unset. Windows uses `%APPDATA%\mocco\credentials.json`. Files permit only the current user. Expired access tokens refresh automatically. `mocco logout` revokes the refresh token before removing the saved entry; if revocation fails, retry logout.

## Choose values and overrides

```sh
mocco secrets run --env staging --path /api -- node server.js
mocco secrets run --keep-env -- yarn dev
mocco secrets run --strict -- yarn test
```

Secrets overwrite inherited environment variables by default. `--keep-env` preserves inherited values instead. Unresolved references produce warnings with key names and reasons only; `--strict` stops before starting the command or writing output. On macOS and Linux, command arguments are passed literally and commands keep an available controlling terminal even with piped or redirected stdin; keyboard Ctrl+C reaches the command once. Windows resolves executable and `.cmd` tools through `PATH` and `PATHEXT` and escapes shim arguments. The CLI forwards termination to the child process group on macOS and Linux, preserves exit status and signal, and uses process-tree termination where needed on Windows.

For a person, `--workspace` and `--project` override linked IDs. `--env` overrides `MOCCO_ENV`, then the linked environment; `--path` overrides the linked folder. `--api-url` overrides `MOCCO_API_URL`, then defaults to `https://www.mocco.club/api/ext/v1`. Only HTTPS and local loopback HTTP URLs are accepted.

## Use an API key in CI

Create a secret API key with `secrets:read`, bound to the required secret environment and folder glob. Store it in your CI provider's secret storage as `MOCCO_API_KEY` and run:

```sh
mocco whoami
mocco secrets run --strict -- yarn build
```

A set `MOCCO_API_KEY` always wins over saved sign-in credentials. An invalid or empty key fails without trying your account. The key chooses its project. Environment and folder defaults still come from flags, `MOCCO_ENV` (environment only), then `.mocco.json`; every request must fit the key’s environment and folder grant. `whoami` reports its project, scopes, secret environment ID and folder glob.

In GitHub Actions, masks and both child output streams share one ordered stdout log channel. The CLI pipes child stdout and stderr into that channel after all masks, so an independent stderr pipe cannot expose a value before its mask. Child stdin stays inherited, and exit codes and signals are preserved. Outside GitHub Actions, stdout and stderr behave as usual.

Prefer `run` in CI. CI stdout is the job log; use the child tool’s file-output option, such as `--output result.json`, to capture structured data instead of a stdout pipeline. `pull` requires an explicit `--output` file in GitHub Actions and refuses direct stdout before requesting secrets. JSON files remain valid JSON; mask commands go to the ordered job log. Never put `pull` output into a step output or print a secret file in a job log.

## Export a file explicitly

```sh
mocco secrets pull --output .env.local
mocco secrets pull --format json --output secrets.local.json
mocco secrets pull --env development
```

`pull` prints dotenv to standard output unless `--output` is set. GitHub Actions requires `--output` as described above. JSON output is one object of strings. Files use UTF-8 and LF, restrictive permissions, and atomic replacement. Dotenv files include a provenance comment; JSON stays valid JSON. The console and CLI share dotenv quoting, including multiline values.

Within a Git repository, add the destination to `.gitignore` first. The CLI refuses both unignored paths and files already tracked by Git, even if an ignore pattern matches. `--force` bypasses these Git protections; it still refuses symlinks. Shell redirection such as `> .env` is managed by your shell and does not receive these file protections.