> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fjall.io/llms.txt
> Use this file to discover all available pages before exploring further.
# fjall secret
> Manage Fjall application secrets in AWS SSM Parameter Store: set, get, list, and delete values.
## Overview
The `fjall secret` command manages secrets stored in AWS SSM Parameter Store. Secrets are namespaced by application and optionally by cluster and service for fine-grained access control.
You can also use the `secrets` alias: `fjall secrets set KEY=value --app myapp`
## Usage
```bash theme={null}
fjall secrets [options]
```
## Subcommands
### set
Set a secret value:
```bash theme={null}
fjall secrets set KEY=value --app myapp
```
Set a secret value from a file:
```bash theme={null}
fjall secrets set KEY -f /path/to/file --app myapp
```
Example:
```bash theme={null}
fjall secrets set DATABASE_PASSWORD=mysecretpassword --app myapp
```
### get
Retrieve a secret value:
```bash theme={null}
fjall secrets get KEY --app myapp
```
Example:
```bash theme={null}
fjall secrets get DATABASE_PASSWORD --app myapp
```
Output is just the value, suitable for piping:
```bash theme={null}
export DB_PASS=$(fjall secrets get DATABASE_PASSWORD --app myapp)
```
### list / ls
List all secrets in a namespace:
```bash theme={null}
fjall secrets list --app myapp
```
With child namespaces:
```bash theme={null}
fjall secrets list --app myapp --all
```
Output:
```
Listing secrets in /myapp
✓ Found 3 secret(s):
Name Path Last Modified
---------------- ----------------------- -------------------
DATABASE_URL /myapp/DATABASE_URL 2024-01-15 10:30:45
API_KEY /myapp/API_KEY 2024-01-15 10:30:45
JWT_SECRET /myapp/JWT_SECRET 2024-01-15 10:30:45
```
### delete / rm
Delete a secret:
```bash theme={null}
fjall secrets delete KEY --app myapp --force
```
Deletion is permanent. The `--force` flag is required in non-interactive mode.
### export
Export secrets in dotenv format:
```bash theme={null}
fjall secrets export --app myapp
```
Output:
```
DATABASE_URL="postgres://..."
API_KEY="sk_live_..."
JWT_SECRET="..."
```
Values are double-quoted, with embedded quotes, backslashes, dollar signs, backticks, and newlines escaped.
Save to file:
```bash theme={null}
fjall secrets export --app myapp > .env.production
```
### exec
Execute a command with secrets as environment variables:
```bash theme={null}
fjall secrets exec --app myapp -- npm start
```
This fetches all secrets in the namespace and injects them as environment variables before running the command.
### import
Import secrets from a `.env` file:
```bash theme={null}
fjall secrets import --app myapp
```
Example:
```bash theme={null}
fjall secrets import .env.production --app myapp
```
The file path is required; omitting it produces `Error: File path is required`.
## Options
| Option | Description | Example |
| ------------------------ | -------------------------------------------------------- | ------------------------- |
| `-a, --app ` | Target application (required) | `--app myapp` |
| `-c, --cluster ` | Optional cluster namespace | `--cluster prod` |
| `-s, --service ` | Optional service namespace | `--service api` |
| `-l, --lambda ` | Scope secrets to a Lambda function | `--lambda ImageProcessor` |
| `-f, --from-file ` | Read secret value from a file (for `set`) | `-f ./secret.pem` |
| `--format ` | Export format: `json`, `dotenv`, `env` (default: dotenv) | `--format json` |
| `--all` | Include child namespaces when listing | `--all` |
| `-f, --force` | Skip confirmation for delete | `--force` |
| `-v, --verbose` | Show detailed output | `-v` |
| `--non-interactive` | Disable prompts | `--non-interactive` |
The `-f` short flag has different meanings depending on the subcommand: `--from-file` for `set` and `--force` for `delete`. Use the long form to avoid ambiguity.
## Namespace Hierarchy
Secrets are organised in a hierarchical namespace:
```
myapp/ # Application level
myapp/prod/ # Cluster level
myapp/prod/api/ # Service level
myapp/lambda// # Lambda function level
```
The cluster name `lambda` is reserved — it marks Lambda-scoped paths in the
hierarchy. Use `--lambda ` for Lambda secrets; `--cluster lambda`
is rejected.
Inheritance applies only to `fjall secrets exec` and `fjall secrets export`: these merge secrets from parent namespaces (app → cluster → service, with more specific values overriding). Deployed workloads do not inherit — an ECS service reads only its exact `////` path, and a Lambda only `//lambda//`. App-level secrets are never injected into containers.
## Non-Interactive Mode
For CI/CD pipelines, use the `--non-interactive` flag with all required options:
```bash theme={null}
# Set a secret
fjall secrets set API_KEY=sk_live_xxx --app myapp --non-interactive
# Get a secret
fjall secrets get API_KEY --app myapp --non-interactive
# List secrets
fjall secrets list --app myapp --non-interactive
# Delete (requires --force)
fjall secrets delete API_KEY --app myapp --force --non-interactive
# Export
fjall secrets export --app myapp --non-interactive
```
## Secret Naming Rules
Secret names must:
* Start with a letter or underscore
* Contain only letters, numbers, underscores, hyphens, or periods
Valid examples:
* `DATABASE_URL`
* `API_KEY_V2`
* `database-url`
* `my.secret`
* `_internal_flag`
Invalid examples:
* `2FA_CODE` (starts with a number)
* `my secret` (contains a space)
## Security
* Secrets are stored encrypted in AWS SSM Parameter Store (SecureString type)
* Access is controlled via IAM policies
* Secrets are displayed in plain text only when you explicitly request them (`get`, `export`) or inject them into a process environment (`exec`); they are never written to logs
* Use namespace hierarchy for least-privilege access
## Examples
### Set multiple secrets
```bash theme={null}
fjall secrets set DATABASE_URL=postgres://... --app myapp
fjall secrets set REDIS_URL=redis://... --app myapp
fjall secrets set API_KEY=sk_live_... --app myapp
```
### Local development with secrets
```bash theme={null}
# Export to .env file
fjall secrets export --app myapp > .env.local
# Or run directly with secrets
fjall secrets exec --app myapp -- npm run dev
```
### CI/CD pipeline
```bash theme={null}
# GitHub Actions example
- name: Deploy with secrets
run: |
fjall secrets exec --app myapp --non-interactive -- fjall deploy myapp
```
### Service-specific secrets
```bash theme={null}
# Set a secret for a specific service
fjall secrets set STRIPE_KEY=sk_live_... --app myapp --cluster prod --service payments
# Get service-specific secret
fjall secrets get STRIPE_KEY --app myapp --cluster prod --service payments
```
## Troubleshooting
### Permission Denied
```bash theme={null}
Failed to get secret: Insufficient permissions to access SSM Parameter Store
```
**Cause**: IAM role doesn't have access to the parameter.
**Solution**: Ensure your AWS credentials have `ssm:GetParameter` permission for the parameter's ARN.
### Secret Not Found
```bash theme={null}
Failed to get secret: Secret 'KEY' not found in namespace
```
**Cause**: Secret doesn't exist or wrong namespace.
**Solution**: Use `fjall secrets list --app myapp` to see available secrets.
### Invalid Secret Name
```bash theme={null}
Error: Invalid key=value format
```
**Cause**: The secret name doesn't follow the naming rules.
**Solution**: Start the name with a letter or underscore and use only letters, numbers, underscores, hyphens, or periods.
## Next Steps
Deploy your application to AWS with its secrets attached.
Connect the AWS account that stores secrets in SSM Parameter Store.
Grant the IAM permissions needed to read and write secrets.
Add an AWS Secrets Manager resource to your infrastructure.