Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

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.

For service-scoped secrets, also remove the key from the service’s infrastructure.ts ssmSecrets declaration — a declaration pointing at a deleted parameter breaks the next task launch:

fjall secrets delete KEY --app myapp --cluster prod --service api --force --remove-declaration

Without the flag, an interactive delete of a service-scoped key asks whether to remove the declaration too.

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

Option	Description	Example
`-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`
`--all`	Include child namespaces when listing	`--all`
`-f, --force`	Skip confirmation for delete	`--force`
`--remove-declaration`	Also remove the key from `infrastructure.ts` on delete	`--remove-declaration`
`-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/<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.

Applying Changes to Running Services

ECS tasks read secret values when they start — updating a parameter does not change what already-running tasks see.

Rotated an existing secret? Restart the running services so new tasks pick up the value. After a successful set or import on a terminal, the CLI offers this directly (Apply to myapp's running services now? (Y/n)); it is also available standalone:
fjall rollout myapp
See fjall rollout — no build, no deploy, and the restart shows which services were running with stale values before you confirm.
Added a new key? Run a full deploy so the task definition gains the reference (when you pass --cluster/--service, the CLI adds the declaration to your infrastructure.ts automatically):
fjall deploy myapp

A plain fjall deploy after rotating an existing value is usually a no-op — unchanged code produces an unchanged image, so nothing restarts. Use fjall rollout, which always rolls the running services.

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.

Core Commands

Infrastructure Codemods

Management Commands

Authentication

Agent Mode

fjall secret

Overview

Usage

Subcommands

set

get

list / ls

delete / rm

export

exec

import

Options

Namespace Hierarchy

Applying Changes to Running Services

Non-Interactive Mode

Secret Naming Rules

Security

Examples

Set multiple secrets

Local development with secrets

CI/CD pipeline

Service-specific secrets

Troubleshooting

Permission Denied

Secret Not Found

Invalid Secret Name

Next Steps

Deploy an application

Connect an AWS account

Configure a deployment user

Secrets Manager resource

​Overview

​Usage

​Subcommands

​set

​get

​list / ls

​delete / rm

​export

​exec

​import

​Options

​Namespace Hierarchy

​Applying Changes to Running Services

​Non-Interactive Mode

​Secret Naming Rules

​Security

​Examples

​Set multiple secrets

​Local development with secrets

​CI/CD pipeline

​Service-specific secrets

​Troubleshooting

​Permission Denied

​Secret Not Found

​Invalid Secret Name

​Next Steps

Deploy an application

Connect an AWS account

Configure a deployment user

Secrets Manager resource

Overview

Usage

Subcommands

set

get

list / ls

delete / rm

export

exec

import

Options

Namespace Hierarchy

Applying Changes to Running Services

Non-Interactive Mode

Secret Naming Rules

Security

Examples

Set multiple secrets

Local development with secrets

CI/CD pipeline

Service-specific secrets

Troubleshooting

Permission Denied

Secret Not Found

Invalid Secret Name

Next Steps