|
1 | 1 | --- |
2 | | -title: Configuration Reference |
3 | | -description: Complete reference for secretspec.toml configuration |
| 2 | +title: secretspec.toml Reference |
| 3 | +description: Complete reference for secretspec.toml configuration options |
4 | 4 | --- |
5 | 5 |
|
6 | | -SecretSpec uses two configuration files: |
7 | | -- **`secretspec.toml`** - Project-specific secret requirements (checked into version control) |
8 | | -- **`config.toml`** - Global user configuration (stored in user config directory) |
| 6 | +## secretspec.toml Reference |
9 | 7 |
|
10 | | -## secretspec.toml Format |
| 8 | +The `secretspec.toml` file defines project-specific secret requirements. This file should be checked into version control. |
| 9 | + |
| 10 | +### [project] Section |
11 | 11 |
|
12 | 12 | ```toml |
13 | 13 | [project] |
14 | 14 | name = "my-app" # Project name (required) |
15 | 15 | revision = "1.0" # Format version (required, must be "1.0") |
16 | | -extends = ["../shared"] # Optional inheritance |
17 | | - |
18 | | -[profiles.default] # Default profile (required) |
19 | | -DATABASE_URL = { description = "PostgreSQL connection", required = true } |
20 | | -API_KEY = { description = "External API key", required = true } |
21 | | -REDIS_URL = { description = "Redis cache", required = false, default = "redis://localhost:6379" } |
| 16 | +extends = ["../shared"] # Paths to parent configs for inheritance (optional) |
22 | 17 | ``` |
23 | 18 |
|
24 | | -### Key Fields |
25 | | - |
26 | | -| Section | Field | Type | Required | Description | |
27 | | -|---------|-------|------|----------|-------------| |
28 | | -| `[project]` | `name` | string | Yes | Project identifier | |
29 | | -| | `revision` | string | Yes | Must be "1.0" | |
30 | | -| | `extends` | array | No | Paths to parent configs | |
31 | | -| `[profiles.*]` | `description` | string | Yes | Secret purpose | |
32 | | -| | `required` | boolean | Yes* | Is value required? | |
33 | | -| | `default` | string | No** | Fallback value | |
| 19 | +| Field | Type | Required | Description | |
| 20 | +|-------|------|----------|-------------| |
| 21 | +| `name` | string | Yes | Project identifier | |
| 22 | +| `revision` | string | Yes | Format version (must be "1.0") | |
| 23 | +| `extends` | array[string] | No | Paths to parent configuration files | |
34 | 24 |
|
35 | | -*Unless `default` is provided |
36 | | -**Only when `required = false` |
| 25 | +### [profiles.*] Section |
37 | 26 |
|
38 | | -## Global Configuration |
39 | | - |
40 | | -Located at: |
41 | | -- **Linux/macOS**: `~/.config/secretspec/config.toml` |
42 | | -- **Windows**: `%APPDATA%\secretspec\config.toml` |
| 27 | +Defines secret variables for different environments. At least a `[profiles.default]` section is required. |
43 | 28 |
|
44 | 29 | ```toml |
45 | | -[defaults] |
46 | | -provider = "keyring" # Default provider |
47 | | -profile = "development" # Default profile |
| 30 | +[profiles.default] # Default profile (required) |
| 31 | +DATABASE_URL = { description = "PostgreSQL connection", required = true } |
| 32 | +API_KEY = { description = "External API key", required = true } |
| 33 | +REDIS_URL = { description = "Redis cache", required = false, default = "redis://localhost:6379" } |
48 | 34 |
|
49 | | -[projects.my-app] |
50 | | -provider = "1password://vault/Production" |
| 35 | +[profiles.production] # Additional profile (optional) |
| 36 | +DATABASE_URL = { description = "Production database", required = true } |
51 | 37 | ``` |
52 | 38 |
|
53 | | -### Provider URIs |
| 39 | +#### Secret Variable Options |
| 40 | + |
| 41 | +Each secret variable is defined as a table with the following fields: |
| 42 | + |
| 43 | +| Field | Type | Required | Description | |
| 44 | +|-------|------|----------|-------------| |
| 45 | +| `description` | string | Yes | Human-readable description of the secret | |
| 46 | +| `required` | boolean | No* | Whether the value must be provided (default: true) | |
| 47 | +| `default` | string | No** | Default value if not provided | |
54 | 48 |
|
55 | | -| Provider | Simple | URI Examples | |
56 | | -|----------|--------|--------------| |
57 | | -| Keyring | `keyring` | `keyring:` | |
58 | | -| 1Password | `1password` | `1password://vault`<br>`1password://vault/Production` | |
59 | | -| Dotenv | `dotenv` | `dotenv:`<br>`dotenv:/path/to/.env` | |
60 | | -| Env | `env` | `env:` | |
61 | | -| LastPass | `lastpass` | `lastpass://folder` | |
| 49 | +*If `default` is provided, `required` defaults to false |
| 50 | +**Only valid when `required = false` |
62 | 51 |
|
63 | | -## Practical Example |
| 52 | +## Complete Example |
64 | 53 |
|
65 | 54 | ```toml |
66 | 55 | # secretspec.toml |
67 | 56 | [project] |
68 | 57 | name = "web-api" |
69 | 58 | revision = "1.0" |
| 59 | +extends = ["../shared/secretspec.toml"] # Optional inheritance |
70 | 60 |
|
| 61 | +# Default profile - always loaded first |
71 | 62 | [profiles.default] |
72 | 63 | APP_NAME = { description = "Application name", required = false, default = "MyApp" } |
73 | 64 | LOG_LEVEL = { description = "Log verbosity", required = false, default = "info" } |
74 | 65 |
|
| 66 | +# Development profile - extends default |
75 | 67 | [profiles.development] |
76 | | -DATABASE_URL = { description = "Database", required = false, default = "sqlite://./dev.db" } |
| 68 | +DATABASE_URL = { description = "Database connection", required = false, default = "sqlite://./dev.db" } |
77 | 69 | API_URL = { description = "API endpoint", required = false, default = "http://localhost:3000" } |
| 70 | +DEBUG = { description = "Debug mode", required = false, default = "true" } |
78 | 71 |
|
| 72 | +# Production profile - extends default |
79 | 73 | [profiles.production] |
80 | | -DATABASE_URL = { description = "PostgreSQL cluster", required = true } |
81 | | -API_URL = { description = "Production API", required = true } |
82 | | -SENTRY_DSN = { description = "Error tracking", required = true } |
| 74 | +DATABASE_URL = { description = "PostgreSQL cluster connection", required = true } |
| 75 | +API_URL = { description = "Production API endpoint", required = true } |
| 76 | +SENTRY_DSN = { description = "Error tracking service", required = true } |
| 77 | +REDIS_URL = { description = "Redis cache connection", required = true } |
83 | 78 | ``` |
84 | 79 |
|
85 | | -## Configuration Precedence |
| 80 | +## Profile Inheritance |
86 | 81 |
|
87 | | -1. Command-line flags (`--provider`, `--profile`) |
88 | | -2. Environment variables (`SECRETSPEC_PROVIDER`, `SECRETSPEC_PROFILE`) |
89 | | -3. Project config (`[projects.{name}]`) |
90 | | -4. Global defaults (`[defaults]`) |
91 | | -5. Built-in defaults |
| 82 | +- All profiles automatically inherit from `[profiles.default]` |
| 83 | +- Profile-specific values override default values |
| 84 | +- Use the `extends` field in `[project]` to inherit from other secretspec.toml files |
0 commit comments