Write and restore secrets
The CLI write verbs write to a project × environment with the same guarantees as the web UI: every write is a new version, merge never deletes missing keys, and re-running is a safe no-op.
`secrets set` — one key
$ movitera secrets set API_KEY=abc123 -p my-app -e development
# or without the value on the command line (no-echo prompt / stdin):
$ cat key.pem | movitera secrets set TLS_KEY -p my-app -e production --comment "cert 2026"The response says what happened: created, updated, or "already had that value — nothing written". Resubmitting the same value and comment is idempotent and does not create a new version.
`secrets upload` — a whole .env
$ movitera secrets upload .env -p my-app -e development
# in CI, without a prompt:
$ movitera secrets upload .env -p my-app -e development --yes- The CLI shows the server preview — counts of new, changed, and same — and asks for confirmation; outside an interactive terminal, confirmation is required via
--yes. - Files with more than 1000 keys are automatically sliced into sequential batches, and the result is printed as a sum.
- Always merge: keys absent from the file are never deleted — running again in CI is a safe no-op.
`secrets history` and `secrets rollback`
$ movitera secrets history DATABASE_URL -p my-app -e production
$ movitera secrets rollback DATABASE_URL --version 4 -p my-app -e production- History lists versions newest first; use
--limit Nto see more. - Rollback appends a new version with the restored value — it never rewrites the past.
Restore from a listed number
Version numbers increase per key, but they are not contiguous and do not necessarily start at 1 — a deleted and recreated key continues numbering from where it left off. Pass a number listed by secrets history, never a calculated one.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Usage error or local failure — includes a write refused without confirmation. |
| 2 | API or network failure — the server message is forwarded with a hint by error code. |
| 126 / 127 | run: command not executable / not found. |
Use in CI with a deploy token
- 1
Create a scoped token in the web app.
In Project settings → Deploy token, create a token bound to the project × environment — least privilege: for read-only, the read scope is enough; writes need the write scope.
- 2
Store it in the CI secret store as `MOVITERA_TOKEN`.
- 3
In the job, address via environment variables and run.
text# .github/workflows/deploy.yml (excerpt) env: MOVITERA_TOKEN: ${{ secrets.MOVITERA_TOKEN }} MOVITERA_PROJECT: my-app MOVITERA_ENV: production steps: - run: movitera run -- ./deploy.sh
- A scoped token only works on project routes — legacy Vault routes reject it.
- Leaked? The blast radius is one environment, not the vault.
- The owner's permissions are re-evaluated on every call — revoking the owner's access demotes the token immediately.
- Token reads produce hour-grouped audit entries with a counter — a hot loop does not pollute the team's history.