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, pick the
Scope: one environment (my-app / production) or the whole project (my-app (all environments)). ClickGenerate tokenand copy the value; it will not be shown again. There is no read or write choice: the token reads and writes with the access its owner has on that environment. For least privilege, bind the token to a single environment. - 2
Store it in the CI secret store as `MOVITERA_TOKEN`.
- 3
In the job, address via environment variables and run.
If the repository already has a
movitera.yamlwith the team, you can leaveMOVITERA_TEAMout. With neither, the job fails withNo team selected.text# .github/workflows/deploy.yml (excerpt) env: MOVITERA_TOKEN: ${{ secrets.MOVITERA_TOKEN }} MOVITERA_TEAM: <team-id> MOVITERA_PROJECT: my-app MOVITERA_ENV: production steps: - run: movitera run -- ./deploy.sh
- A deploy token only works with projects (
-p/-e,movitera.yaml, or the project variables).-ccredentials,creds list,totp,team list,whoami, and the TUI refuse it. - Leaked? The damage stays within the token's scope: one environment or one project, never the whole 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.