Skip to content
xecret
Sign in

Importing and exporting secrets

Move secrets in and out of xecret — .env, JSON, YAML and shell formats, conflict strategies, dry runs, and migrating from another secret manager.

Updated 2026-08-16 · read this page as markdown

On this page

Getting your existing configuration in, and getting it out again if you ever want to leave. Both matter: a secret manager you cannot export from is a secret manager that has taken your configuration hostage.

Importing from the dashboard

Open a project, pick an environment, and drag your file into the import dialog.

The file is parsed in your browser. A dry-run preview shows exactly what will be created, renamed or skipped, and only the resulting plan is sent — so a pasted blob of production credentials never becomes a request body.

Supported formats, auto-detected:

FormatLooks like
dotenvKEY=value, with or without export , quotes, and # comments
jsonA flat object of string values
yamlA flat mapping
shellA script of export KEY=value lines

Multiline PEM blocks, CRLF line endings and trailing comments all parse the way you would hope.

Importing from the CLI

bash
xecret import .env --dry-run
xecret import .env --strategy overwrite
xecret import config.json --format json
FlagEffect
--formatForce a parser instead of detecting one
--strategy skip(default) leave existing names alone
--strategy overwriteappend a new version for names that already exist
--strategy renameimport under a suffixed name, keeping both
--dry-runprint the plan and write nothing
--jsonmachine-readable output

Always dry-run first against a production environment. The preview is produced by the same planning code the real import runs, so it cannot disagree with the outcome.

Files are limited to 1 MB, and a single secret value to 64 KB.

Names that need fixing

Secret names must match your shell's rules: letters, digits and underscores, never starting with a digit. If your source file has my-key or 2fa-secret, the import reports them rather than silently mangling them. Rename them in the source file and import again — a rename you did not choose is a rename you will be debugging at 3am.

Exporting

bash
xecret pull --format env
xecret pull --format json | jq 'keys'
xecret pull --format yaml -o config.yaml     # created 0600
FormatOutput
envKEY=value lines, quoted where needed
jsonone object
yamlone mapping
shellexport KEY=value lines, for source
dockerthe shape docker run --env-file expects

The dashboard has the same thing under the environment's export dialog, as a file download.

Migrating from another tool

From .env files

The whole job:

bash
xecret import .env --dry-run          # look at the plan
xecret import .env                    # do it
rm .env                               # and mean it
echo ".env*" >> .gitignore

Then replace the run command in your scripts — see Node.js, Next.js or Go.

If different developers have drifted apart, collect one canonical file first: diff two colleagues' .env files and reconcile before importing. The import is a good moment to notice that half the team has a stale Stripe key.

From another secret manager

Most tools can export a flat .env or JSON. Export one environment at a time, import it into the matching xecret environment, and verify before deleting anything:

bash
other-tool export --env production > production.env
xecret import production.env --environment production --dry-run
xecret import production.env --environment production

# verify: the names should match, one for one
diff <(sort -t= -k1,1 production.env | cut -d= -f1) \
     <(xecret pull --environment production --format env | cut -d= -f1 | sort)

shred -u production.env      # or rm, on a filesystem where that is enough

Do one environment at a time, starting with development. Migrating production first is how a migration becomes an incident.

Keeping both for a transition period

While you are moving over, it is reasonable to run both. Make xecret the source of truth immediately and sync outwards from it — never the reverse — so there is never a question about which copy is current:

bash
xecret pull --format env | other-tool import --env production

What is not exported

  • Version history. pull gives you the current value of each secret. Older versions stay in xecret; there is no bulk history export.
  • Notes, value types, and grants. These are metadata about how the environment is managed, not configuration your app reads.
  • The audit log. Available through the API for owners and admins.

Next