CLI
anchor is the command-line client for Anchor. Developers use it to log in, link a directory to a
project, manage secrets and run commands with secrets injected. CI uses it with a service token.
Install
Section titled “Install”npm, Homebrew and the install script all install two commands, anchor and anchor-secrets.
They are the same program. Use anchor-secrets when another tool already owns anchor on your
PATH (see Troubleshooting).
npm (macOS, Linux, Windows)
Section titled “npm (macOS, Linux, Windows)”Needs Node.js 22.19 or later.
npm install -g @anchor-secrets/clinpx @anchor-secrets/cli --help # or run it without installingHomebrew (macOS, Linux)
Section titled “Homebrew (macOS, Linux)”brew install sotarak/tap/anchorInstall script (macOS, Linux)
Section titled “Install script (macOS, Linux)”curl -fsSL https://sotarak.github.io/anchor/install.sh | shThe script picks the release binary for your platform, verifies it against the release’s
SHA256SUMS, and installs it to ~/.local/bin without sudo. Nothing is installed if the checksum
does not match. Read it first if you pipe scripts to sh. Options are environment variables:
| Variable | Default | Purpose |
|---|---|---|
ANCHOR_VERSION |
latest |
Version to install, 0.2.0 or v0.2.0 |
ANCHOR_INSTALL_DIR |
~/.local/bin |
Target directory |
ANCHOR_DOWNLOAD_BASE |
https://github.com/sotarak/anchor/releases |
Release mirror |
curl -fsSL https://sotarak.github.io/anchor/install.sh | ANCHOR_VERSION=0.2.0 shRelease binaries
Section titled “Release binaries”Every GitHub Release has single-file binaries
(anchor-darwin-arm64, anchor-darwin-x64, anchor-linux-x64, anchor-linux-arm64,
anchor-windows-x64.exe) and a SHA256SUMS file. Check the binary against SHA256SUMS, make it
executable, and put it on your PATH as anchor (anchor.exe on Windows). This is the
Windows install path when Node.js is not available.
From the workspace
Section titled “From the workspace”pnpm --filter ./apps/cli buildwritesapps/cli/dist/anchor.mjs, the same single file the npm package ships (node apps/cli/dist/anchor.mjs --help).pnpm --filter ./apps/cli dev <args>runs the TypeScript source withtsx(development).
In CI, use the setup action.
Upgrade and uninstall
Section titled “Upgrade and uninstall”Upgrade with the tool you installed with. anchor --version shows what you have.
| Installed with | Upgrade | Uninstall |
|---|---|---|
| npm | npm install -g @anchor-secrets/cli@latest |
npm uninstall -g @anchor-secrets/cli |
| Homebrew | brew update && brew upgrade anchor |
brew uninstall anchor |
| Install script | run the script again (ANCHOR_VERSION pins a version) |
rm ~/.local/bin/anchor ~/.local/bin/anchor-secrets |
| Release binary | download the new binary over the old one | delete the binary |
| Setup action | bump sotarak/anchor/setup-action@v<version> |
remove the step |
Before you uninstall, run anchor logout: it revokes the session on the server and removes the
stored credential from the keychain (or the fallback file). Uninstalling alone leaves both behind.
The install script uses ANCHOR_INSTALL_DIR in place of ~/.local/bin if you set it.
Getting started
Section titled “Getting started”anchor login --api-url https://anchor.example.com # approve in the browsercd my-appanchor init # pick a project and default environmentanchor secrets set DATABASE_URL # hidden prompt for the valueanchor run -- npm start # npm start sees DATABASE_URLanchor login stores a CLI session (valid 30 days) in your OS keychain and remembers the API URL in
your user config. anchor init writes .anchor.json, which is meant to be committed.
Logging in
Section titled “Logging in”anchor login logs in through the browser, like gh auth login:
- It prints
Open https://<server>/cli/login and enter the code WDJB-MJHTand, in a terminal, opens that page (--no-browseronly prints it). - On the page, signed in to the dashboard, type the code from your terminal, check the device details and click Approve. The link never carries the code: never enter a code someone sent you, since approving signs their terminal in as you.
- The CLI, which polls every 5 seconds, stores the session. The request expires after 10 minutes.
It works over SSH and in containers: open the URL on any device. Only a dashboard session can
approve a request. Login was denied in the browser and
Login request expired; run anchor login again exit with code 3. Against a server older than
0.4.0 it says This server does not support browser login; use anchor login --with-password.
anchor login --with-password keeps the email and password flow; --email and
--password-stdin imply it, so existing scripts keep working. CI should use ANCHOR_TOKEN.
Commands
Section titled “Commands”Run anchor <command> --help for the options and examples of each command.
get, run and export expand references and include the
folder’s imports by default; --no-expand uses the stored values. History and rollback are
described in Versions and rollback.
| Command | Purpose |
|---|---|
anchor login [--no-browser] [--with-password] [--email <email>] [--password-stdin] |
Log in (in the browser by default) and store a CLI session |
anchor logout |
Revoke the stored session on the server and delete it locally |
anchor whoami |
Show the current user or service token |
anchor init |
Link the current directory to a project (writes .anchor.json) |
anchor projects list |
List the projects you can access |
anchor envs list |
List the environments of the current project |
anchor secrets list [--reveal] |
List secrets with their type and metadata (sensitive values only with --reveal) |
anchor secrets get <key> [--reveal] [--no-expand] [--at-version <n>] |
Print one secret; a sensitive value is masked in a terminal unless --reveal |
anchor secrets history <key> |
List the versions of a secret (no values) |
anchor secrets rollback <key> --to <n> |
Restore a past version as a new version |
anchor secrets set <key> [--from-file <path>] [--comment <text>] [--type <type>] [--sensitive | --no-sensitive] |
Create or update a secret |
anchor secrets import [--from-file <path>] [--format dotenv|json|yaml] [--overwrite] [--non-sensitive <glob>]... [--comment <text>] [--dry-run] |
Import a dotenv, JSON or YAML file into the current environment and path |
anchor secrets delete <key> |
Delete a secret |
anchor folders list |
List the subfolders of --path (default /) |
anchor folders create <path> |
Create a folder and its parents (no-op if it exists) |
anchor folders delete <path> [--force] |
Delete an empty folder; --force deletes its contents too |
anchor imports list |
List the folders --path imports, in the order they apply |
anchor imports add <env>:<path> |
Make --path show the secrets of another folder (no-op if it already does) |
anchor imports remove <env>:<path> |
Stop importing a folder |
anchor run [--no-override] [--no-expand] [--allow-reserved] [--pass-token] [--watch [--watch-interval <s>]] -- <command> [args...] |
Run a command with secrets in its environment |
anchor export [--format dotenv|json|yaml] [--output <file>] [--no-expand] [--allow-reserved] |
Write secrets to a file or a pipe |
anchor tokens create --name <name> [--scope <env[:path]>]... [--permission read|read-write] [--expires-in <days|never>] |
Create a service token (never: valid until revoked) |
anchor tokens list |
List the project’s service tokens |
anchor tokens revoke <id> |
Revoke a service token |
Value types and plain config
Section titled “Value types and plain config”Every secret has a type: string (the default), json, pem, number, boolean or list (a
JSON array of strings), and is either sensitive (the default) or plain config:
printf 8080 | anchor secrets set APP_PORT --type number --no-sensitiveanchor secrets set JWT_KEYS --from-file keys.json --type jsonanchor secrets set TLS_CERT --from-file cert.pem --type pemsetchecks the value against its type before sending it, and fails withValue of <KEY> is not valid for type <type>: <reason>(exit 2) without printing the value. Without--typeor--sensitive/--no-sensitive, the secret keeps its current type and flag (a new secret is a sensitivestring).secrets listhas a TYPE column. Non-sensitive values are shown without--reveal; sensitive ones show********unless you pass--reveal.secrets getprints a non-sensitive value without--revealtoo.- References (
${...}) expand only instringvalues; typed values are always used as stored.
Import a file
Section titled “Import a file”anchor secrets import loads a whole file into one environment and folder (--env, --path, or
.anchor.json), so a service can move to anchor run without one secrets set per key.
- Format comes from
--format, otherwise from the name:.jsonis JSON,.yaml/.ymlis YAML, and.env,*.envor a name starting with.env(.env.production) is dotenv. Piped stdin, or any other name, needs--format. - dotenv values are imported as
string, byte for byte; nothing is guessed. - JSON and YAML must hold an object. Nested keys are joined with
_and uppercased, with-,.and spaces turned into_:configs.openrouter.api_keybecomesCONFIGS_OPENROUTER_API_KEYandtransporters.grpc-clientsbecomesTRANSPORTERS_GRPC_CLIENTS. Types are inferred: numbers arenumberand keep the text written in the file (1.0stays1.0; a YAML number such as0x1For.infis imported as astring),true/falseareboolean, an array of strings islist, any other array isjson, a PEM block ispem, and other strings arestring. A blank value (api_key:) or an empty object is reported as empty and nothing is created for it. - Before anything is sent, the whole file is checked; a key that is not a valid Anchor key
(
Cannot import 2fa: 2FA is not a valid key), two paths that map to the same key (a.b-c and a.b_c both become A_B_C), or a value over 64 KiB or invalid for its type stops the import with exit 2. Every problem is listed at once, and values are never printed. - Existing keys are skipped and listed as
skip.--overwritewrites a new version for them with the imported type and flag (a key whose value, type, flag and comment are already the same is reported as unchanged). Without--comment, an overwritten key keeps its comment. - Sensitivity: every key is sensitive unless it matches a
--non-sensitive <glob>(*and?, case-sensitive, matched against the final key; repeat the flag for more globs). - Writes go one at a time, in key order. On the first failure the import stops with exit 1 and
Imported <n> of <m>; <KEY> failed: <error>. Re-run to continue; a re-run skips the keys already written. - Output is a KEY, TYPE, SENSITIVE and ACTION table, then
Created <a>, updated <b>, skipped <c> existing, <d> empty in <env>:<path>.--dry-runprints the same table withDry run: would create ...and writes nothing. Values are never shown.
For example, moving zepo-engine’s shared config and one service’s .env into prod:
anchor secrets import --from-file application.config.yaml --env prod --path /shared \ --non-sensitive 'CONFIGS_CONTEXT_*' --non-sensitive 'CONFIGS_AGENT_*' --dry-run# check the plan, then run it again without --dry-runanchor secrets import --from-file apps/service-agent/.env --env prod --path /service-agentThen replace each value in application.config.yaml with its placeholder
(api_key: ${CONFIGS_OPENROUTER_API_KEY}) and start the service with anchor run.
Imports
Section titled “Imports”anchor imports manages imports: a folder that also
shows the secrets of another folder. It is not anchor secrets import, which loads a file.
anchor imports add prod:/shared --env prod --path /api # /api now also shows /sharedanchor imports list --env prod --path /api # 1 prod:/sharedanchor imports remove prod:/shared --env prod --path /api- The source is
<env>:<path>, written like a reference without the key.sharedalone meansshared:/, andshared:dbmeansshared:/db. - The folder is
--envand--path(defaults from.anchor.json). addis idempotent: adding an import that exists printsAlready imports ...and exits 0.removeasks for confirmation, because the folder’s apps lose those keys on their next read. Without a terminal it requires--yes. A source the folder does not import exits 5 and lists the imports it has.
Handling of secret values
Section titled “Handling of secret values”- Values are never accepted as command-line arguments.
anchor secrets set KEY=valueand any--valueflag are rejected (exit 2) without echoing the value.setreads the value from--from-file(exact bytes), from piped stdin (one trailing newline removed), or from a hidden prompt. Any second positional or=aftersecrets set(also after--) is rejected the same way. An empty stdin exits 2 so</dev/nullcannot blank a secret; set an empty value with--from-fileand an empty file. secrets getprints the raw value (no added newline) when stdout is a pipe or a file. In a terminal it shows a sensitive value masked unless you pass--reveal; a masked view does not read the value from the server, so it is not recorded as a secret read.anchor runfetches secrets before starting the command. If the fetch fails (network error, expired session, missing permission) the command is not started.SIGTERMandSIGHUPare forwarded to the command;SIGINTis forwarded only when there is no terminal (at a terminal, Ctrl-C already reaches the command, and a second one would force-quit many tools).anchorexits with the command’s exit code (127 when the command is not found, 128 + N when it was killed by signal N). By default Anchor values replace existing environment variables;--no-overridekeeps existing ones. The command must follow--(exit 2 otherwise, so a child’s--env prodis never read as Anchor’s); everything after--is passed unchanged. On Windows,.cmdshims such asnpmare resolved throughPATHEXT.anchor runnever injects a secret whose name changes how programs load code or where they connect:PATH,NODE_OPTIONS,LD_*/DYLD_*,PYTHONPATH,JAVA_TOOL_OPTIONS,GIT_SSH*,*_PROXY,ANCHOR_*and similar (case-insensitive; the full list isisReservedEnvKeyin the SDK). It printsSkipped reserved names: <names> (pass --allow-reserved to inject them)and runs the command without them;--allow-reservedinjects them anyway. Otherwise anyone who can write to the folder could run code whereveranchor runruns.anchor runremoves an inheritedANCHOR_TOKENfrom the command’s environment, so a build script cannot read the CI token. Pass--pass-tokenwhen the command itself callsanchoror the SDK with it.anchor exportrefuses to print to a terminal. With--outputit writes the file with mode 0600 (also when it replaces an existing file), asks before overwriting (--yesin scripts), and warns when the file is not gitignored.--format dotenvwrites only lines that a dotenv parser reads back exactly and that a shell or docker-compose sourcing the file never runs or expands. A value it cannot write that way (one with a'or a newline together with$, a backtick,"or\, or a trailing\) fails with a hint: use--format jsonor--format yamlfor such values. Reserved names (as foranchor run) are left out of dotenv files with a warning;--allow-reservedwrites them.--format jsonand--format yamlwrite typed values: anumberas a number, abooleanastrue/false, alistas an array and ajsonvalue as its JSON.dotenvandanchor runalways use the stored text (PORT=8080,MODELS=["a","b"]).--debugprints one line per request (debug: GET /api/v1/... -> 200 (12ms)): never headers, bodies, tokens or values.
Restart on changes: anchor run --watch
Section titled “Restart on changes: anchor run --watch”anchor run --watch -- npm run devanchor run --watch --watch-interval 10 --env staging -- node server.jsWith --watch, anchor run keeps checking Anchor while the command runs and restarts the
command when its secrets change:
- The first fetch works as without
--watch: if it fails, the command is not started. - Every
--watch-intervalseconds (default 30, minimum 5, a whole number) the CLI asks Anchor whether the folder changed, withIf-None-Match. An unchanged folder costs a304with no body and no audit row, so watching is cheap. - When the environment the command would get differs, stderr shows
Secrets changed; restarting <command>(never keys or values). The command getsSIGTERM; if it has not exited after 10 seconds it getsSIGKILL. Then it starts again with the new values. Only one copy of the command ever runs. A change that leaves the environment as it was (a comment, or a key that--no-overridehides) does not restart it. - When a check fails (network error, server error, expired or revoked token), the command keeps
running with the values it has. The first failure prints
Could not check Anchor for changes (<reason>); keeping the current values, and the first check that works again printsReconnected to Anchor. - When the command exits on its own,
anchorstops watching and exits with the command’s code.SIGINT,SIGTERMandSIGHUPreach the command as without--watch, so stoppinganchorstops both. - On Windows,
SIGTERMends the command at once: there is no grace period. --watch-intervalwithout--watch, or a value that is not a whole number of at least 5, exits 2.
Only secrets are watched; to restart on file changes too, run a file watcher (such as nodemon)
under anchor run --watch.
Destructive commands
Section titled “Destructive commands”secrets delete, folders delete, imports remove, tokens revoke, init over an existing .anchor.json and export --output over
an existing file ask for confirmation in a terminal. Without a terminal they require --yes and exit
2 otherwise.
Global flags
Section titled “Global flags”| Flag | Meaning |
|---|---|
--json |
Print one JSON document on stdout (see “JSON output”) |
-q, --quiet |
Suppress progress messages on stderr |
--no-color |
Disable colored output |
--debug |
Print request diagnostics to stderr (never secret values) |
--api-url <url> |
Anchor server URL |
--project <slug> |
Project slug |
--env <slug> |
Environment slug |
--path <path> |
Secret folder path (/, /api, …) |
-y, --yes |
Skip confirmations |
--version, -h, --help |
Version and help |
Global flags work before or after the command name. stdout carries data only; progress, prompts,
hints, warnings and errors go to stderr. Color is used only on a terminal, and never when NO_COLOR
is set, TERM=dumb, or --no-color is given.
Configuration
Section titled “Configuration”Precedence, highest first: flags > ANCHOR_* environment variables > .anchor.json > user
config > defaults (env = dev, path = /, no default API URL).
.anchor.json
Section titled “.anchor.json”anchor init writes it in the current directory; commands find the nearest one by walking up from
the working directory. It holds identifiers only and is safe to commit:
{ "version": 1, "project": "my-app", "defaultEnv": "dev", "path": "/", "apiUrl": "https://anchor.example.com"}defaultEnv, path and apiUrl are optional (init writes apiUrl only when you passed
--api-url). The CLI refuses a file with unknown keys, and refuses a file that contains any string
starting with anc_ (a token): remove it and rotate the token.
User config
Section titled “User config”$XDG_CONFIG_HOME/anchor/config.json, else ~/.config/anchor/config.json (macOS, Linux), or
%APPDATA%\anchor\config.json (Windows). It holds { "apiUrl": "..." }, written by the first
anchor login and replaced by anchor login --api-url.
API URL
Section titled “API URL”The URL is reduced to its origin. https:// is required, except for localhost, 127.0.0.1 and
[::1]. anchor login always prints the server it is logging in to. When the URL comes only from
.anchor.json and differs from your user config, it warns and asks before logging in
(Log in to <url>?, or Send your password to <url>? with --with-password; without a terminal it
exits 2 unless you pass --api-url or --yes), and it never saves that URL as your user config.
anchor login --api-url <url> makes <url> your default server, and prints
Default server changed from <old> to <new> when it replaces another one, for example after you
move a deployment to a custom domain. ANCHOR_API_URL and .anchor.json never change the default;
the first only fills it when you have none. Sessions for the old server stay stored until you run
anchor logout --api-url <old>. anchor login --json reports the result as defaultApiUrl.
Environment variables
Section titled “Environment variables”| Variable | Meaning |
|---|---|
ANCHOR_API_URL |
API URL |
ANCHOR_PROJECT, ANCHOR_ENV, ANCHOR_PATH |
Project, environment and path |
ANCHOR_TOKEN |
Service token for CI; takes precedence over a stored login |
ANCHOR_CREDENTIAL_STORE |
auto (default) or file |
NO_COLOR |
Disable color |
HTTPS_PROXY, HTTP_PROXY, NO_PROXY |
Proxy settings (see “Proxy”) |
ANCHOR_TOKEN is only sent to an API URL that comes from --api-url, ANCHOR_API_URL or your
user config. If the only API URL is the one in .anchor.json, the CLI exits 2: a pull request
cannot redirect your CI token to another host. Set ANCHOR_API_URL in CI.
Credential storage
Section titled “Credential storage”| Platform | Store |
|---|---|
| macOS | Login keychain (service anchor-cli, account = API origin), written through security -i on stdin |
| Linux with a desktop session | Secret Service (GNOME Keyring, KWallet) through secret-tool, token on stdin |
Everything else, or ANCHOR_CREDENTIAL_STORE=file |
<user config dir>/credentials.json, mode 0600 in a 0700 directory |
Tokens never appear in process arguments. When the keychain cannot be written, the CLI falls back to
the file and warns. The CLI refuses to read a credentials file that other users can access (run
chmod 600 on it). anchor logout revokes the session on the server, then deletes it locally; if
the server cannot be reached it still deletes the local copy, exits 1 and tells you until when the
session stays valid.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
Success |
1 |
Error |
2 |
Usage error (bad flag or argument, missing --yes without a terminal, refused configuration) |
3 |
Not logged in, session expired or revoked, invalid credentials or token |
4 |
Forbidden |
5 |
Not found |
6 |
Conflict |
anchor run exits with the command’s own code instead (127: not found; 128 + N: killed by signal
N). These codes are a stable contract.
JSON output
Section titled “JSON output”With --json, stdout holds exactly one JSON document. Fields may be added in later versions;
existing fields are not renamed or removed without a major version.
| Command | Shape |
|---|---|
login |
{ apiUrl, user, expiresAt, credentialStore, defaultApiUrl } (never the token) |
logout |
{ loggedOut, revoked } |
whoami |
{ apiUrl, type: "user", user } or { apiUrl, type: "service_token", serviceToken } |
init |
{ projectFile, project, defaultEnv } |
projects list |
{ projects: ProjectDto[] } |
envs list |
{ environments: EnvironmentDto[] } |
secrets list |
{ secrets: SecretDto[] } (value with --reveal, and for non-sensitive secrets) |
secrets get |
{ secret: SecretDto } (value only with --reveal or when stdout is not a terminal) |
secrets set |
{ secret: SecretDto, created: boolean } (never the value) |
secrets delete |
{ deleted: { key, environment, path } } |
secrets import |
{ created, updated, unchanged, skipped, empty } (arrays of keys; empty holds source paths; dryRun: true with --dry-run, where the arrays hold the planned keys) |
imports list |
FolderImportDto[] |
imports add |
{ import: FolderImportDto, created: boolean } |
imports remove |
{ removed: FolderImportDto } |
export --output |
{ path, count, format } (without --output, use --format json instead of --json) |
tokens create |
{ serviceToken: ServiceTokenDto, token } |
tokens list |
{ serviceTokens: ServiceTokenDto[] } |
tokens revoke |
{ revoked: id } |
The DTO types are defined in packages/shared/src/api.ts. Errors are not JSON: they go to stderr
as error: <message> and hint: <next step>.
Network behavior
Section titled “Network behavior”Each request times out after 15 seconds. GET and PUT (secret writes are idempotent) are retried
at most twice, after 250 ms and 1 s, on network errors and on HTTP 429, 502, 503 and 504. POST and
DELETE are never retried. Redirects are never followed (the token would go with them): an API
URL that answers with one fails with <origin> answered with a redirect (HTTP 302); use the final address as the API URL.
The CLI honors HTTPS_PROXY, HTTP_PROXY and NO_PROXY (lowercase variants too). On Node it routes
requests through undici’s EnvHttpProxyAgent when one of these is set. The Bun release binaries use
Bun’s own proxy support for the same variables.
CI jobs authenticate with a service token in ANCHOR_TOKEN; see Use Anchor in CI.