Fjall Docs — deploy AWS infrastructure into your own account

Overview

fjall restore starts an AWS Backup restore job for an S3 bucket, EBS volume, RDS database or EC2 instance. The restore runs inside AWS Backup, not CloudFormation. Fjall starts the job and hands you the job ID plus a console link, then AWS Backup does the work.

Prerequisites

Requirement	How to satisfy it
A Fjall session	`fjall login`
A connected AWS account	`fjall connect`
A completed recovery point	See Finding recovery points
Matching organisation binding	Run inside a project bound to the same organisation as your Fjall credential

Usage

fjall restore [resource] [options]

Arguments

Argument	Description	Required
`resource`	Resource type to restore: `s3`, `ebs`, `rds`, or `ec2`	Yes in one-shot mode, ignored in the picker

An unrecognised value exits immediately with Error: Invalid resource type '<value>' and the list of valid types.

Options

Option	Description	Example
`--recovery-point <arn>`	Recovery point ARN. Required in one-shot mode	`--recovery-point arn:aws:backup:...`
`-n, --name <name>`	Name for the restored resource. RDS only	`--name restored-db`
`--backup-vault <name>`	Vault holding the recovery point. Defaults to `Default`	`--backup-vault fjall-vault`
`-y, --yes`	Skip the agent-mode dry run and start the restore immediately	`-y`
`-v, --verbose`	Enable verbose logging	`-v`
`--non-interactive`	Force plain CLI output and run the restore in one shot	`--non-interactive`

-n, --name applies to RDS restores only — it becomes the restored instance’s DBInstanceIdentifier. Passing it with s3, ebs or ec2 is refused, because those resources take the name AWS Backup derives from the recovery point and there is nowhere to put one. The name must satisfy AWS’s identifier rules: 1 to 63 characters, letters and digits only apart from separating hyphens, starting with a letter, no trailing hyphen and no two consecutive hyphens. Underscores, dots and spaces are refused.

Fjall reads the recovery point’s own restore metadata before starting the job, because AWS Backup requires the settings the backup was taken with. That read looks in the Default vault unless you name another with --backup-vault. The interactive picker already knows the vault it selected, so the flag is for one-shot and agent runs.

Agent flags

These flags shape output for AI agents and scripted callers.

Flag	Description
`--agent`	Enable agent output mode
`--budget <level>`	Output budget: `minimal`, `compact`, or a token count
`--fields <fields>`	Request additional fields in output
`--full`	Disable content truncation

Interactive or one-shot

Fjall picks the mode from the terminal, not from the arguments you pass.

Condition	What runs
stdout is a TTY, no `--non-interactive`, no `--agent`	The guided picker, starting at step 1
`--non-interactive`, `--agent`, or piped/redirected stdout	A one-shot restore from the flags

The picker ignores resource and --recovery-point. On a normal terminal, fjall restore rds --recovery-point arn:... opens the picker at “What type of resource would you like to restore?” and those flags are discarded. Add --non-interactive whenever you want them honoured. -n, --name is the exception: the picker seeds its Database instance name: prompt with it, and you can still edit it there. If you pass it and then pick a type that cannot carry a name, the restore is refused at the confirmation rather than starting without it.

Interactive restore

fjall restore

The picker steps through:

Resource category (What type of resource would you like to restore?): Compute or Storage.
Resource type (Select compute resource type: for EC2, or Select storage resource type: for S3, EBS, RDS).
Backup vault (Select backup vault (N available):): each vault shows its recovery-point count.
Resource (Select resource to restore (N available):): shows the backup count and latest backup date.
Recovery point (Select a backup to restore (N available for <resource>):): the most recent backup is labelled (Latest).
Confirmation (Start restore job?, defaults to Yes): shown after a review list of Resource Type, Resource Name, Recovery Point and Backup Vault.

RDS adds two prompts before the confirmation: Database instance name: under the heading Configure Restore Settings, then Database port: under Configure Database Port (1 to 65535, default 3306). The name prompt is pre-filled with -n, --name when you passed one, otherwise with the identifier the recovery point was taken from, otherwise with <resource>-restored. It is always editable, and the flag seeds it once: step back from the port prompt and the prompt re-offers what you typed, not the flag.

One-shot restore

For CI/CD and scripting, pass the resource type, the recovery point and --non-interactive:

fjall restore rds \
  --recovery-point arn:aws:backup:ap-southeast-2:123456789012:recovery-point:abc-123 \
  --name orders-restored \
  --non-interactive

A one-shot run has no confirmation prompt and no dry run. It starts the restore job as soon as the recovery point validates. Agent mode is the exception: --agent previews the restore as a dry run and reports Dry-run — pass --yes to initiate restore. Add -y to apply it.

fjall restore rds \
  --recovery-point arn:aws:backup:ap-southeast-2:123456789012:recovery-point:abc-123 \
  --agent --yes

What happens

==> [1/3] Validating recovery point
  Recovery Point: arn:aws:backup:ap-southeast-2:123456789012:recovery-point:abc-123
  Resource Type: RDS
<== [1/3] Validating recovery point (1.4s)

==> [2/3] Initiating restore job
  ✓ Restore job ID: A1B2C3D4-5678-90AB-CDEF-EXAMPLE11111
<== [2/3] Initiating restore job (2.1s)

<== [3/3] Completing restore

── Summary ───────────────────────────────────────
  Result:   ✓ Restore job started successfully
  Duration: 3.7s

Next steps:
  • View progress: https://console.aws.amazon.com/backup/home?region=ap-southeast-2#/jobs/restore/A1B2C3D4-5678-90AB-CDEF-EXAMPLE11111
  • Import restored resource: fjall import

Important (RDS):
  • The restored database keeps the password from when the snapshot was taken — it is NOT reset to the current Secrets Manager value. Reconcile credentials before applications connect (reset the DB master password to match the secret, or update the secret to the snapshot-era password), then restart the application's services so running containers pick up the reconciled values: fjall rollout <app>.

Resource types

S3 bucket

fjall restore s3 \
  --recovery-point arn:aws:backup:ap-southeast-2:123456789012:recovery-point:abc-123 \
  --non-interactive

EBS volume

fjall restore ebs \
  --recovery-point arn:aws:backup:ap-southeast-2:123456789012:recovery-point:abc-123 \
  --non-interactive

RDS database

Restores an RDS instance or an Aurora cluster.

fjall restore rds \
  --recovery-point arn:aws:backup:ap-southeast-2:123456789012:recovery-point:abc-123 \
  --non-interactive

AWS Backup restores run outside CloudFormation, so the restored database keeps the master password from when the snapshot was taken. It is not reset to the current Secrets Manager value. Reconcile credentials before applications connect: reset the database master password to match the secret, or update the secret to the snapshot-era password. Then run fjall rollout <app> so running containers pick up the reconciled values.

EC2 instance

fjall restore ec2 \
  --recovery-point arn:aws:backup:ap-southeast-2:123456789012:recovery-point:abc-123 \
  --non-interactive

Finding recovery points

Two ways to get an ARN:

AWS Console: Backup, then Protected resources, then select a resource.

AWS CLI, through Fjall-minted credentials:

fjall aws exec --target production-apse2 -- \
  aws backup list-recovery-points-by-resource \
  --resource-arn arn:aws:rds:ap-southeast-2:123456789012:db:api-database

The interactive picker finds them for you, vault by vault, so you rarely need to look one up by hand.

After a restore

Track the job with the console link the CLI prints, or in AWS Console, Backup, Jobs.
Reconcile database credentials (RDS only). The restored database keeps the snapshot-era master password, not the current Secrets Manager value. Restart services afterwards with fjall rollout <app>.
Update application configuration if the restored resource has a new name or endpoint.
Adopt the resource into an application with fjall import.

fjall import adopts existing AWS resources into a Fjall application, but adoption is currently S3-only. Discovery spans S3, Lambda, ECS, RDS, EC2, ElastiCache and VPC, while anything other than an S3 bucket is refused with UNSUPPORTED_RESOURCE_TYPE. Track restored EBS volumes, RDS databases and EC2 instances manually for now.

Troubleshooting

Permission denied

Ensure you have the following permissions:
  - backup:StartRestoreJob
  - backup:GetRecoveryPointRestoreMetadata
  - iam:PassRole (for the restore role)

Grant the IAM permissions listed in Required permissions to the role Fjall assumes for the target account.

—name applies to rds restores only

--name applies to rds restores only, not s3. A restored s3 resource takes the name AWS Backup derives from the recovery point.

Drop -n, --name. Only RDS restores carry a caller-chosen name; the other three types are named by AWS Backup from the recovery point, and the flag is refused rather than accepted and ignored.

Failed to get restore metadata

Failed to get restore metadata: Backup vault not found. Looked in the 'Default' vault; name its vault with --backup-vault if it is held elsewhere.

Fjall reads the recovery point’s restore metadata from the Default vault unless told otherwise, and the message names the vault it looked in. Pass --backup-vault <name> naming the vault the recovery point actually lives in — fjall aws exec --target <target> -- aws backup list-backup-vaults lists them. If you already passed --backup-vault the message says so, and the vault named is the one to check.

No restore metadata

The recovery point in the 'Default' vault reports no restore metadata, and AWS Backup will not restore without the parameters the backup was taken with.

The vault answered, and had nothing to say about that recovery point — usually an ARN from another vault, or a recovery point that has not finished. Check the ARN names a COMPLETED point in the vault you passed.

Recovery point not found

Verify the recovery point ARN is correct

Confirm the ARN is valid and the recovery point still exists:

fjall aws exec --target production-apse2 -- \
  aws backup describe-recovery-point \
  --backup-vault-name Default \
  --recovery-point-arn arn:aws:backup:ap-southeast-2:123456789012:recovery-point:abc-123

Recovery point ARN is required

Error: Recovery point ARN is required in non-interactive mode. Use --recovery-point flag

You reached the one-shot path without an ARN. Either supply --recovery-point, or drop --non-interactive and use the picker on a real terminal. CI shells hit this whenever stdout is redirected.

Restore job failed

The CLI reports only that the job started. AWS Backup owns the outcome:

Open AWS Console, Backup, Jobs.
Find the failed job by its ID.
Read the status message for the failure reason.

Required permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "backup:StartRestoreJob",
        "backup:DescribeRestoreJob",
        "backup:GetRecoveryPointRestoreMetadata",
        "backup:ListBackupVaults",
        "backup:ListRecoveryPointsByBackupVault"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::*:role/service-role/AWSBackupDefaultServiceRole"
    }
  ]
}

backup:GetRecoveryPointRestoreMetadata is read on every restore: AWS Backup will not start a restore job without the parameters the backup was taken with, so Fjall reads them from the recovery point when you have not supplied them yourself. ListBackupVaults and ListRecoveryPointsByBackupVault are what the interactive picker browses. Fjall defaults the restore role to arn:aws:iam::<account-id>:role/service-role/AWSBackupDefaultServiceRole.

Next Steps

fjall import

Adopt a restored S3 bucket into a Fjall application.

fjall rollout

Restart services after reconciling restored database credentials.

fjall tunnel

Open a secure tunnel to a restored database.

fjall connect

Connect an AWS account before restoring its resources.

​Overview

​Prerequisites

​Usage

​Arguments

​Options

​Agent flags

​Interactive or one-shot

​Interactive restore

​One-shot restore

​What happens

​Resource types

​S3 bucket

​EBS volume

​RDS database

​EC2 instance

​Finding recovery points

​After a restore

​Troubleshooting

​Permission denied

​—name applies to rds restores only

​Failed to get restore metadata

​No restore metadata

​Recovery point not found

​Recovery point ARN is required

​Restore job failed

​Required permissions

​Next Steps

fjall import

fjall rollout

fjall tunnel

fjall connect

Overview

Prerequisites

Usage

Arguments

Options

Agent flags

Interactive or one-shot

Interactive restore

One-shot restore

What happens

Resource types

S3 bucket

EBS volume

RDS database

EC2 instance

Finding recovery points

After a restore

Troubleshooting

Permission denied

—name applies to rds restores only

Failed to get restore metadata

No restore metadata

Recovery point not found

Recovery point ARN is required

Restore job failed

Required permissions

Next Steps