opschain secret migrate
Included from Basic tier
opschain secret migrate [--mount <kv-mount>] [--apply]
Re-encrypts every plaintext, {AES} and {AES2}/U value in the secret
backend with the configured customer transportable key, writing field by
field and preserving sibling fields — the remediation step for what
opschain secret audit reports. Values already {AES2}/T are left
untouched; {AES2}/T values the key cannot decrypt are skipped and reported
as unrecoverable, never overwritten.
Dry run by default. Without --apply the plan is printed and nothing is
written. --apply writes to the shared secret vault that live changes read
from — run it deliberately, outside heavy change traffic.
Backend and transportable-key selection are exactly as opschain secret audit resolves them: the vault: block of
$OPSCHAIN_HOME/server/config.yaml over the OPSCHAIN_VAULT_* environment,
with the key from vault.transportable_key, vault.transportable_key_path
or OPSCHAIN_TRANSPORTABLE_KEY_PATH. See opschain docs cli/secret-audit. A
transportable key is mandatory here — there is nothing to migrate to
without one.
Flags
| Flag | Meaning |
|---|---|
--mount <kv-mount> | KV v1 mount to migrate (openbao/hashicorp backends only; default: the configured mount). |
--apply | Perform the re-encryption writes (without it the plan is printed and nothing is written). |
Output
One line per value — <path>.<field>: <from> -> {AES2}/T for a (planned)
migration, UNRECOVERABLE — …; skipped and FAILED — … lines where
applicable — then the summary, e.g. for a dry run:
migration of age file store /home/user/.opschain/secrets/store.age: 3 to migrate, 7 already {AES2}/T, 0 unrecoverable (skipped), 0 failed
dry run — nothing was written; re-run with --apply to perform the migration
Exit codes
| Code | Meaning |
|---|---|
| 0 | Planned (dry run) or migrated; unrecoverable values are skipped, not failures. |
| 1 | The migration failed, no transportable key is configured, or at least one value failed to migrate. |
| 2 | Usage error. |
Named errors
no transportable key is configured — there is nothing to migrate to (set vault.transportable_key or vault.transportable_key_path in config.yaml, or OPSCHAIN_TRANSPORTABLE_KEY_PATH).<n> value(s) failed to migrate(exit 1).--mount applies to the openbao/hashicorp backend; the age file store has no mounts(exit 2).
See also
opschain docs cli/secret-audit— classify before you migrate, and verify afterwards.opschain learn 3.5— secrets and vault, guided.