SDK Reference

Python SDK

The secr-sdk Python package provides a synchronous client for the secr API. Built on httpx, it offers full type safety with Python dataclasses.

Installation

pip install secr-sdk

Requires Python 3.9+.

Quick Start

quickstart.py

from secr import SecrClient

client = SecrClient(token="secr_cli_...")

# Pull secrets
result = client.pull_secrets("my-org", "my-project", "production")
for s in result.secrets:
    print(f"{s.key}={s.value}")

# Set a secret
client.set_secret("my-org", "my-project", "dev", "API_KEY", "sk-...")

# Context manager (auto-closes HTTP client)
with SecrClient(token="...") as client:
    result = client.pull_secrets("my-org", "my-project", "dev")

Configuration

config.py

client = SecrClient(
    token="secr_cli_...",             # Required
    api_url="https://api.secr.dev",   # Default
    timeout=30.0,                     # Seconds, default 30
)

Option	Type	Required	Description
token	str	Yes	secr CLI token (secr_cli_...)
api_url	str	https://api.secr.dev	API base URL
timeout	float	30.0	Request timeout in seconds

API Reference

pull_secrets(org, project, env, *, limit, offset, search)

Pull decrypted secrets for an environment.

Example

result = client.pull_secrets("org", "proj", "production")
result.secrets     # list[Secret] -- .key, .value, .version, .updated_at
result.pagination  # Optional[PaginationInfo] -- .limit, .offset, .total

list_keys(org, project, env, *, limit, offset, search)

List secret key names without values.

Example

result = client.list_keys("org", "proj", "dev")
result.keys  # list[SecretMeta] -- .key, .version, .updated_at

set_secret(org, project, env, key, value)

Create or update a single secret.

Example

result = client.set_secret("org", "proj", "dev", "DB_URL", "postgres://...")
result.key      # "DB_URL"
result.version  # 1 (or incremented)

bulk_set_secrets(org, project, env, secrets)

Set multiple secrets at once.

Example

result = client.bulk_set_secrets("org", "proj", "dev", [
    {"key": "A", "value": "1"},
    {"key": "B", "value": "2"},
])
result.created  # Number of new secrets
result.updated  # Number of updated secrets
result.total    # Total processed

delete_secret(org, project, env, key)

Soft-delete a secret.

Example

result = client.delete_secret("org", "proj", "dev", "OLD_KEY")
result.deleted  # True

promote_secrets(org, project, *, from_env, to_env, keys, overwrite)

Copy secrets between environments.

Example

result = client.promote_secrets(
    "org", "proj",
    from_env="staging",
    to_env="production",
    overwrite=True,
)
result.promoted  # Total promoted
result.created   # New in target
result.updated   # Overwritten in target
result.skipped   # Skipped (existed, no overwrite)

list_templates(org, project)

List secret templates for a project.

Example

templates = client.list_templates("org", "proj")
for t in templates:
    print(f"{t.key} (required={t.required})")

validate_template(org, project, env)

Check if an environment has all required secrets.

Example

result = client.validate_template("org", "proj", "production")
result.valid    # bool
result.missing  # list[str]
result.extra    # list[str]

Error Handling

All API errors are raised as SecrApiError:

errors.py

from secr import SecrClient, SecrApiError

try:
    client.pull_secrets("org", "proj", "dev")
except SecrApiError as e:
    print(e.message)       # Human-readable message
    print(e.status_code)   # HTTP status (0 for network errors)
    print(e.code)          # Error code: "unauthorized", "not_found", "timeout", etc.

Property	Type	Description
message	str	Human-readable error message
status_code	int	HTTP status code (0 for network errors)
code	str	Error code: "unauthorized", "not_found", "timeout", etc.

Types

All response types are Python dataclasses:

Class	Fields
Secret	key, value, version, updated_at
SecretMeta	key, version, updated_at
PaginationInfo	limit, offset, total
PullSecretsResult	secrets, pagination
ListKeysResult	keys, pagination
SetSecretResult	key, version
BulkSetSecretsResult	created, updated, total
DeleteSecretResult	deleted, key
PromoteResult	promoted, created, updated, skipped
Template	id, key, description, required, created_at
TemplateValidation	valid, missing, extra

Start building with the Python SDK

pip install secr-sdk

Create Free Account Back to Docs