Skip to main content

​
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

fjall secrets <subcommand> [options]

​
Subcommands

​
set

Set a secret value: 
fjall secrets set KEY=value --app myapp
Set a secret value from a file: 
fjall secrets set KEY -f /path/to/file --app myapp
Example: 
fjall secrets set DATABASE_PASSWORD=mysecretpassword --app myapp

​
get

Retrieve a secret value: 
fjall secrets get KEY --app myapp
Example: 
fjall secrets get DATABASE_PASSWORD --app myapp
Output is just the value, suitable for piping: 
export DB_PASS=$(fjall secrets get DATABASE_PASSWORD --app myapp)

​
list / ls

List all secrets in a namespace: 
fjall secrets list --app myapp
With child namespaces: 
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: 
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: 
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: 
fjall secrets export --app myapp > .env.production

​
exec

Execute a command with secrets as environment variables: 
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: 
fjall secrets import <file> --app myapp
Example: 
fjall secrets import .env.production --app myapp
The file path is required; omitting it produces Error: File path is required.

​
Options

OptionDescriptionExample
-a, --app <name>Target application (required)--app myapp
-c, --cluster <name>Optional cluster namespace--cluster prod
-s, --service <name>Optional service namespace--service api
-l, --lambda <name>Scope secrets to a Lambda function--lambda ImageProcessor
-f, --from-file <path>Read secret value from a file (for set)-f ./secret.pem
--format <type>Export format: json, dotenv, env (default: dotenv)--format json
--allInclude child namespaces when listing--all
-f, --forceSkip confirmation for delete--force
-v, --verboseShow detailed output-v
--non-interactiveDisable 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/<function>/    # Lambda function level
The cluster name lambda is reserved — it marks Lambda-scoped paths in the hierarchy. Use --lambda <function> 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 /<app>/<cluster>/<service>/ path, and a Lambda only /<app>/lambda/<function>/. App-level secrets are never injected into containers.

​
Non-Interactive Mode

For CI/CD pipelines, use the --non-interactive flag with all required options: 
# 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

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

# 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

# GitHub Actions example
- name: Deploy with secrets
  run: |
    fjall secrets exec --app myapp --non-interactive -- fjall deploy myapp

​
Service-specific secrets

# 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

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

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

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 an application

Deploy your application to AWS with its secrets attached.

Connect an AWS account

Connect the AWS account that stores secrets in SSM Parameter Store.

Configure a deployment user

Grant the IAM permissions needed to read and write secrets.

Secrets Manager resource

Add an AWS Secrets Manager resource to your infrastructure.