CLI Identity Reference

Managing signing keys and identities is critical for secure deployment pipelines. Caatinga interfaces with the Stellar CLI identity manager.

$ --source Parameter Validation Rules

Stellar Identity Security

Caatinga strictly mandates that the --source flag MUST specify a valid identity alias configured in the Stellar CLI (e.g., alice), never raw cryptographic keys or seed phrases.

✓Allowed --source Values

✓ alice
✓ bob
✓ deployer-testnet

✗Forbidden --source Values

✗ GABC... (Public Key)
✗ SABC... (Secret Key)
✗ 12-word seed phrase

Commands

`identity export`

Export your whole Stellar CLI config directory (~/.config/stellar by default, or STELLAR_HOME) as a base64-encoded tarball, written to stdout. This is not per-alias — it archives the entire config directory, including every identity stored there.

npx ctg identity export > stellar-config.b64

Flags:

--path <path>: Stellar config directory to archive (default: ~/.config/stellar).

The output is base64, not encrypted. Treat it as key material — pipe it straight into a CI secret store (e.g. CAATINGA_CI_STELLAR_CONFIG_B64) rather than saving it to disk.

`identity import`

Import a base64 tarball produced by identity export into a local environment or CI runner.

npx ctg identity import stellar-config.b64

<archive> is a positional argument: the path to the base64-encoded tarball file (not JSON, not encrypted).

Flags:

--path <path>: Target Stellar config directory to restore into (default: ~/.config/stellar).

Security advisory (fixed in 3.9.2)

Action required if you have ever run ctg identity export or ctg identity import before 3.9.2.

Earlier versions wrote the tarball to os.tmpdir() using a predictable Date.now() filename and default permissions, and never deleted it. That means a world-readable copy of your Stellar secret keys could sit on disk indefinitely. Upgrading to 3.9.2+ stops new leaks — it does not remove archives already on disk. Check every machine and CI image where identity export/import has ever run:

ls -la /tmp/caatinga-stellar-*.tar.gz

Delete anything it lists, and rotate the affected keys if the machine is shared or the files may have been picked up by CI artifact upload or backups.

As of 3.9.2, the archive is written inside a mkdtemp directory created with mode 0700 under a random name, and removed in a finally block — so it cannot outlive the command, even if tar fails. identity import writes the temp archive with mode 0600 and creates the target directory with mode 0700.

Security Best Practices

Never hardcode private keys (S...), seed phrases, or secret environment variables in your codebase. Always export identity aliases via Stellar CLI or rely on identity import in CI pipelines.