sng secret

Available

Deployed and supported. The fields and commands described here are stable within version v1alpha1.

The sng secret group manages the secret values of your tenant: creation, reading, versions, rotation, deletion. It acts on the secrets service, not on your manifests — except for sng secret create, which produces and applies an SSMSecret manifest.

All commands require a session on the tenant (sng tenant use NAME); otherwise: tenant session required: run sng tenant use NAME. The global flags (--config, --json, -v, --version) are described in the CLI index.

Secret name (the NAME argument everywhere): lowercase, digits, ., _, -; at most 128 characters; neither / nor ... Otherwise: invalid secret name: use lowercase letters, digits, dots, underscores or hyphens.

IAM actions per command:

Command	IAM action	Route
list	ssm:list	GET /v1/secrets
describe	ssm:describe	GET /v1/secrets/{name}
get	ssm:read	GET /v1/secrets/{name}/value
set	ssm:write	PUT /v1/secrets/{name}
create	deploy:write (apply); the platform then declares the secret	POST /v1/apply
versions	ssm:describe	GET /v1/secrets/{name}/versions
rotate	ssm:read then ssm:write	GET …/value then PUT /v1/secrets/{name}
restore	ssm:write	POST /v1/secrets/{name}/restore
delete	ssm:delete	DELETE /v1/secrets/{name}

A refusal returns 403 forbidden; a missing session 403 tenant session required.

sng secret list

sng secret list [--json]

Lists the tenant's secrets, without values.

Flag	Type	Default	Description
(no flags of its own)

sng secret list

NAME          KEYS  UPDATED
api-key             2026-10-07T09:12:41Z
db-password         2026-10-07T09:10:03Z

Without secrets: no secrets. The KEYS column is empty in this version (the list does not load the keys; use describe).

--json output: {"secrets": [{"name": "…", "updated_at": "…", "version_id": "3", "version_stages": {"current": "3"}}]}.

sng secret describe

sng secret describe NAME

Metadata of a secret, always in JSON: keys, current version, rotation. Never the value.

Argument	Description
NAME	secret name

sng secret describe db-password

{
  "name": "db-password",
  "keys": ["value"],
  "updated_at": "2026-10-07T09:10:03Z",
  "version_id": "3",
  "rotation_enabled": true,
  "rotation_days": 30,
  "next_rotation_date": "2026-11-06T09:10:03Z",
  "version_stages": { "current": "3" },
  "bindings": {
    "env_from_secret": { "name": "runtime-env", "key": "db-password" },
    "external_secret_remote_ref": { "key": "db-password", "property": "value" }
  }
}

rotation_* and next_rotation_date only appear if a rotation is armed. version_id: "0" indicates a secret declared without a value. The bindings block is a legacy field to ignore.

Errors: secret not found (404) if the secret does not exist or was deleted.

sng secret get

sng secret get NAME [--version-id ID] [--key KEY] [--out-file PATH]

Reads the value of a secret. Without --key, prints the JSON of the keys; with --key, prints the raw value of that key.

Argument	Description
NAME	secret name

Flag	Type	Default	Description
--version-id	string	(current)	version number to read (1, 2, …)
--key	string		extract one key of the secret
--out-file	string		write to this file (permissions 0600) instead of standard output

sng secret get db-password
sng secret get db-password --key value
sng secret get db-password --version-id 1 --key value --out-file ./old

{
  "value": "S3cr3t"
}
S3cr3t
wrote ./old (mode 0600)

The wrote … message is written to standard error. A secret without a value returns null.

Errors: key "x" not found in secret; secret not found (404).

sng secret set

sng secret set NAME [--value V | --from-file PATH | --data K=V ...]
                    [--length N] [--contains CLASSES] [--exclude-chars CHARS]
                    [--no-lowercase] [--no-uppercase] [--no-numbers] [--no-symbols]
                    [--require-each-type[=false]]
                    [--rotation N] [--rotation-key KEY]

Creates or updates a secret (new version). Without --value, --from-file, or --data, a random value is generated (16 characters: letters, digits, punctuation) and stored under the value key.

Argument	Description
NAME	secret name

Flag	Type	Default	Description
--value	string		plaintext value (discouraged: visible in the shell history)
--from-file	string		read the value from a file, as is (recommended)
--data	k=v, repeatable		key=value pairs; the secret then has several keys
--length	int	16	length of the generated value (1–4096)
--contains	list	(all)	classes to use: letter, number, symbol, lower, upper (aliases: letters, alpha, numbers, digit, digits, symbols, punctuation, lowercase, uppercase); mutually exclusive with the --no-* flags
--exclude-chars	string		characters never used
--no-lowercase	bool	false	no lowercase letters
--no-uppercase	bool	false	no uppercase letters
--no-numbers	bool	false	no digits
--no-symbols	bool	false	no punctuation
--require-each-type	bool	true	at least one character from each selected class
--rotation	int	off	the server renews the value every N days (1–3650); 0 disarms; absent = schedule unchanged
--rotation-key	string		key to renew for a multi-key secret (default: its only key); requires --rotation

Rules:

• The generation flags (--length, --contains, --exclude-chars, --no-*, --require-each-type) only apply to a generated value. With a provided value they are refused: --length only applies to a generated value (without --from-file, --data or --value) — except --length, --contains, --exclude-chars, --require-each-type when --rotation is present: they then describe the value the server will generate when it is due.
• --contains and the --no-* flags are mutually exclusive: --contains and the --no-* flags are mutually exclusive.
• --data requires the k=v form: --data format expected key=value.

sng secret set db-password
sng secret set db-password --from-file ./pw --rotation 30 --length 24
sng secret set shop-api --data DATABASE_URL=postgres://… --data SMTP_PASSWORD=xyz

secret "db-password" saved with a generated 16-character value (sng secret get db-password)
secret "db-password" saved
secret "shop-api" saved

--json output: the secret's metadata (same shape as describe, without bindings).

Typical errors: --length 3 is too short to include each of the 4 character types; no characters left to generate a value: relax the --no-* or --exclude-chars options; --rotation-key requires --rotation; value or data required (400, empty body on the API side); forbidden (403).

sng secret create

sng secret create NAME [--length N] [--rotation N] [--contains CLASSES]
                       [--description TEXT] [--dry-run]

Declares a secret by manifest: produces an SSMSecret manifest and applies it like sng apply (tenant of the local configuration required). The platform then creates the secret, generates its value if --length > 0, and will delete it along with the manifest. The value never appears in the manifest. See Declare a secret in a manifest.

Argument	Description
NAME	name of the secret and of the manifest

Flag	Type	Default	Description
--length	int	16	length of the generated value (0–4096); 0 = declared empty, value set afterwards with set
--rotation	int	0	renewal every N days (0–3650); requires --length > 0
--contains	list	(all)	classes: letters, numbers, symbols (aliases letter, alpha, number, digit, digits, numbers, symbol, punctuation); requires --length > 0
--description	string		description visible in describe
--dry-run	bool	false	prints the manifest without applying it

sng secret create db-password --length 20 --rotation 30
sng secret create smtp-password --length 0
sng secret create api-key --contains letters,numbers --dry-run

secret "db-password" declared in tenant acme: …
secret "smtp-password" declared in tenant acme: …
set its value with: sng secret set smtp-password

--dry-run output:

apiVersion: ssm.stackngo.io/v1alpha1
kind: SSMSecret
metadata:
  name: api-key
spec:
  length: 16
  contains:
    - letters
    - numbers

--json output: {"uploads": [...]}.

Typical errors: --rotation needs a generated value: --length must be > 0; --contains needs a generated value: --length must be > 0; --contains "x" unknown: expected letters, numbers or symbols; --length must be between 0 and 4096; --rotation must be between 0 and 3650 days; tenant session required: run sng tenant use NAME.

sng secret versions

sng secret versions NAME [--json]

Lists the versions of a secret (number, date). No value.

Argument	Description
NAME	secret name

sng secret versions db-password

VERSION  STAGES  CREATED
1                2026-10-07T09:10:03Z
2                2026-10-07T09:31:48Z

STAGES is always empty in this version. Secret without a value: no versions.

--json output: {"versions": [{"version_id": "1", "stages": [], "created_at": "…"}]}.

sng secret rotate

sng secret rotate NAME [--key KEY]
                       [--length N] [--contains CLASSES] [--exclude-chars CHARS]
                       [--no-lowercase] [--no-uppercase] [--no-numbers] [--no-symbols]
                       [--require-each-type[=false]]
                       [--rotation N] [--rotation-key KEY]

Replaces the value with a new random value, stored as a new version. Generation happens in the CLI, with the same flags as set. For a multi-key secret, --key designates the renewed key; the others are kept.

Argument	Description
NAME	secret name

Flag	Type	Default	Description
--key	string	(only key)	key to renew in a multi-key secret
generation flags			same as set: --length, --contains, --exclude-chars, --no-*, --require-each-type
--rotation, --rotation-key			same as set: arm or change the scheduled rotation at the same time

sng secret rotate db-password
sng secret rotate shop-api --key SMTP_PASSWORD --length 32
sng secret rotate db-password --rotation 30

secret "db-password" rotated: new 16-character value (sng secret get db-password)
secret "shop-api" rotated: new 32-character value for key "SMTP_PASSWORD"

Typical errors: the secret holds several keys (DATABASE_URL, SMTP_PASSWORD): choose one with --key; key "x" not found in the secret; secret not found (404); forbidden (403, you need ssm:read and ssm:write).

sng secret restore

sng secret restore NAME

Undoes the deletion of a secret: it comes back with its value, all its versions and its rotation schedule. Action ssm:write.

Argument	Description
NAME	secret name

sng secret restore db-password

secret "db-password" restored

Restoring a secret that is not deleted succeeds without changing anything. In this version, no recovery window applies: a deleted secret remains restorable. See Versions and restore.

Typical errors: secret not found (404, no secret of that name in the tenant); forbidden (403, ssm:write is required).

sng secret delete

sng secret delete NAME [--yes] [--force] [--recovery-days N]

Deletes a secret. Asks for confirmation (type oui) unless --yes is given.

Argument	Description
NAME	secret name

Flag	Type	Default	Description
--yes, -y	bool	false	confirm without an interactive prompt
--force	bool	false	immediate deletion without recovery (ignored by the server in this version)
--recovery-days	int	0	recovery window in days (7–30; ignored by the server in this version)

sng secret delete db-password
sng secret delete db-password --yes

⚠ Suppression définitive du secret "db-password".
Tapez « oui » pour confirmer : oui
secret "db-password" scheduled for deletion (recovery 30 d)

With --force: secret "db-password" permanently deleted.

Whatever the flag, the deletion is logical on the server side: the secret disappears from list, describe, and get, its encrypted versions are not purged. sng secret restore NAME puts it back into service with all its versions; a sng secret set NAME recreates it under the same name, continuing the versions.

Typical errors: confirmation requise : relancez avec --yes ou depuis un terminal interactif (non-interactive input without --yes); secret not found (404); forbidden (403).

See also

• Guides: Create and read, Versions and restore, Rotation, Declare in a manifest, Inject into an App
• Manifest: SSMSecret
• Related commands: sng apply, sng kind delete SSMSecret NAME, sng template gen SSMSecret NAME