Secret Commands

kdn manages two related concepts for injecting credentials into workspaces:

• Secret services — Built-in definitions that describe how a credential is injected into outbound HTTP requests. Each service specifies the host pattern to match, the HTTP header to set, and the header value template. Use kdn service list to see the available services.
• Secrets — Named credential entries created with kdn secret create. Each secret has a type (a service name or other), a value stored securely in the system keychain, and optional metadata. Secrets are referenced by name in workspace configuration.

Workflow: 1. Run kdn service list to see available service types (e.g., github) 2. Create a secret: kdn secret create my-github-token --type github --value ghp_xxx 3. Reference the secret by name in workspace configuration: "secrets": ["my-github-token"]

Note: The secret field on environment variable entries (e.g., {"name": "GH_TOKEN", "secret": "github-token"}) is a separate mechanism that references runtime secrets (such as Podman secrets) for injecting values as environment variables. It is useful when a local tool inside the workspace needs a credential via an environment variable. For credentials used in outbound network requests, use the Secret abstraction described here instead — secrets are injected as HTTP headers by OneCLI and are not exposed as environment variables.

service list - List Registered Services¶

Lists all secret services available for workspace configuration.

Usage¶

kdn service list [flags]

Flags¶

• --output, -o <format> - Output format (supported: json)

Examples¶

List all services (human-readable table):

kdn service list

NAME    HOST PATTERN       PATH  HEADER          HEADER TEMPLATE    ENV VARS                DESCRIPTION
github  api.github.com         Authorization   Bearer ${value}    GH_TOKEN, GITHUB_TOKEN  GitHub API token for accessing GitHub repositories and services

List services in JSON format:

kdn service list --output json

{
  "items": [
    {
      "name": "github",
      "description": "GitHub API token for accessing GitHub repositories and services",
      "hostsPatterns": ["api.github.com"],
      "headerName": "Authorization",
      "headerTemplate": "Bearer ${value}",
      "envVars": ["GH_TOKEN", "GITHUB_TOKEN"]
    }
  ]
}

List using short flag:

kdn service list -o json

Notes¶

• Services are defined in the embedded configuration and are always available regardless of runtime or environment
• Each service describes how to inject credentials into HTTP requests for matching hosts

secret create - Create a New Secret¶

Creates a new secret and stores its value securely in the system keychain. Non-sensitive metadata (type, hosts, path, header template, envs) is persisted in the kdn storage directory.

Usage¶

kdn secret create <name> [flags]

Arguments¶

• name - Unique name to identify this secret

Flags¶

• --type <type> - Type of secret: a registered service name (e.g., github) or other (required)
• --value <value> - Secret value to store in the system keychain (required)
• --description <text> - Optional human-readable description
• --host <pattern> - Host pattern (required for --type=other; can be specified multiple times)
• --header <name> - HTTP header name (required for --type=other)
• --headerTemplate <template> - HTTP header value template using ${value} as placeholder (optional, for --type=other)
• --path <path> - URL path restriction (optional, for --type=other)
• --env <name> - Environment variable name to expose the secret value (optional, for --type=other; can be specified multiple times)
• --output, -o <format> - Output format (supported: json)
• --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples¶

Create a GitHub token secret:

kdn secret create my-github-token --type github --value ghp_mytoken

Secret "my-github-token" created successfully

Create a custom secret with all descriptor flags:

kdn secret create my-api-key --type other --value secret123 \
  --host api.example.com --host dev.example.com \
  --path /api/v1 \
  --header Authorization --headerTemplate "Bearer ${value}" \
  --env MY_API_KEY --env API_KEY

Create a custom secret with only required flags:

kdn secret create my-api-key --type other --value secret123 \
  --host api.example.com --header Authorization

Create a secret with JSON output:

kdn secret create my-github-token --type github --value ghp_mytoken --output json

{
  "name": "my-github-token"
}

Notes¶

• --type must be a registered service name (use kdn service list to see available types) or other
• For --type=other, --host and --header are required; all other descriptor flags are optional
• For named types (e.g., github), the descriptor flags (--host, --header, --headerTemplate, --env, --path) must not be specified — those are defined by the service
• The secret value is stored in the system keychain (GNOME Keyring on Linux, Keychain on macOS, DPAPI on Windows) and never written to disk in plain text
• JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure

secret list - List All Secrets¶

Lists all secrets stored in the kdn storage directory.

Usage¶

kdn secret list [flags]

Flags¶

• --output, -o <format> - Output format (supported: json)
• --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples¶

List all secrets (human-readable table):

kdn secret list

NAME              TYPE    DESCRIPTION
my-github-token   github
my-api-key        other   Internal API key

List secrets in JSON format:

kdn secret list --output json

{
  "items": [
    {
      "name": "my-github-token",
      "type": "github",
      "description": ""
    },
    {
      "name": "my-api-key",
      "type": "other",
      "description": "Internal API key",
      "hosts": ["api.example.com"],
      "header": "Authorization",
      "headerTemplate": "Bearer ${value}"
    }
  ]
}

List using short flag:

kdn secret list -o json

Notes¶

• Only metadata is listed; secret values are never displayed
• JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure

secret remove - Remove a Secret¶

Removes a secret from the system keychain and from the kdn storage directory.

Usage¶

kdn secret remove <name> [flags]

Arguments¶

• name - Name of the secret to remove

Flags¶

• --output, -o <format> - Output format (supported: json)
• --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples¶

Remove a secret by name:

kdn secret remove my-github-token

Secret "my-github-token" removed successfully

Remove a secret with JSON output:

kdn secret remove my-github-token --output json

{
  "name": "my-github-token"
}

Remove using the alias:

kdn secret rm my-github-token

Notes¶

• Removing a secret also deletes its value from the system keychain
• Workspaces that reference the removed secret by name will fail to start until a new secret with the same name is created
• JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure