secrets

1ctl secret manages sensitive key-value pairs for your deployments — database passwords, API keys, tokens, and anything else you would not want in plaintext. Secrets are not environment variables. They travel through a different path, are stored differently, and have stricter access controls.

you → 1ctl secret create → POST /v1/cli/secrets → encrypted DB row + K8s Secret object

Values are encrypted with AES-256-GCM before they are written to PostgreSQL. A corresponding Kubernetes Secret is created in the deployment’s namespace and the pod spec references each key explicitly with secretKeyRef, so the values surface as environment variables at runtime — but their values never appear in ConfigMaps, deployment specs, or 1ctl output after the initial create call.

If you need to store something non-sensitive (a log level, a port number, a feature flag), use 1ctl env instead. The distinction matters for compliance, secret rotation, and who can read cluster resources.

Commands

1ctl secret create

1ctl secret create [--deployment-id <id>] [--config <cfg>] [--name <label>] --kv KEY=VALUE ...

Creates a new secret group or updates an existing one for a deployment. Repeating --kv lets you set multiple keys in one call.

Flags

Flag	Short	Default	Description
--kv KEY=VALUE		required	A key-value pair to store. Repeat for multiple keys: --kv A=1 --kv B=2.
--deployment-id <id>		satusky.toml	Deployment to attach the secrets to. Resolved from satusky.toml if omitted.
--name <label>		auto-generated	Human-readable label for the secret group. Useful when a deployment has multiple secret groups.
--config <name>		satusky.toml	Named config file to use (e.g. staging resolves to satusky.staging.toml).

Under the hood:

1. 1ctl sends POST /v1/cli/secrets with the deployment ID, name, and key-value pairs
2. The API encrypts each value with AES-256-GCM and writes a row to the secrets table in PostgreSQL
3. The API creates (or patches) a Kubernetes Secret object in the deployment’s namespace
4. The Kubernetes Secret is referenced by the deployment’s pod spec via explicit secretKeyRef entries — keys become environment variables in every container

After creation, secret values are never returned by any API response. 1ctl secret list shows group metadata only.

secret create updates the Deployment spec as part of the operation, so Kubernetes rolls out fresh pods automatically. Running containers still do not hot-reload environment variables in place; the value appears once the rollout completes.

Examples

# Create secrets for the project in the current directory
1ctl secret create --kv DATABASE_PASSWORD=hunter2 --kv JWT_SECRET=abc123

# Create secrets for a specific deployment
1ctl secret create --deployment-id dep_123abc --kv API_KEY=xyz

# Label the group for easier identification
1ctl secret create --name "database-creds" --kv DB_PASS=s3cr3t --kv DB_USER=app

# Use a staging config
1ctl secret create --config staging --kv STRIPE_KEY=sk_test_abc

---

1ctl secret list

1ctl secret list

Lists all secret groups associated with your deployments. Shows group names, deployment associations, and key names — but never the values.

Under the hood: GET /v1/cli/secrets returns metadata rows from the secrets table. Values are not decrypted or included in the response.

Example

$ 1ctl secret list
GROUP           DEPLOYMENT    KEYS                          CREATED
database-creds  dep_123abc    DB_PASS, DB_USER              2 days ago
api-keys        dep_456def    STRIPE_KEY, SENDGRID_KEY      1 hour ago

---

1ctl secret unset

1ctl secret unset [-d/--deployment-id <id>] [--config <cfg>] -k <key>

Removes a single key from a secret group. The key is deleted from the PostgreSQL secrets table and patched out of the corresponding Kubernetes Secret object.

As with create, secret unset patches the Deployment spec immediately and triggers a rollout so removed keys disappear from replacement pods.

Flags

Flag	Short	Default	Description
-k <key>		required	The key name to remove.
--deployment-id <id>	-d	satusky.toml	Deployment to target. Resolved from satusky.toml if omitted.
--config <name>		satusky.toml	Named config file to use.

Example

# Remove a key from the current project's secrets
1ctl secret unset -k DATABASE_PASSWORD

# Remove from a specific deployment
1ctl secret unset -d dep_123abc -k OLD_API_KEY

Security model

Property	Detail
Encryption at rest (DB)	AES-256-GCM, keyed per-organisation
Encryption at rest (K8s)	etcd encryption enabled on the cluster
Transmission	HTTPS only; value never logged by the API
Post-creation visibility	Key names only — values are never returned
Pod access	secretKeyRef entries on the pod spec; containers see keys as environment variables

Never commit secret values to satusky.toml or any file in your repository. Use 1ctl secret create so values travel encrypted end-to-end.