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

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

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:

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

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.