> ## 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 create

> Create AWS organisation infrastructure, accounts, or applications with the Fjall CLI and ready-to-deploy CDK code.

<Info>
  **Interactive command**: Guides you through creating organisations and applications with smart defaults.
</Info>

## Overview

The `fjall create` command scaffolds AWS infrastructure as CDK TypeScript. It creates standalone account infrastructure (monitoring, compliance), organisational structures (accounts, SSO, billing), or applications (compute, storage, networking).

## Usage

```bash theme={null}
fjall create [target] [options]
```

## Targets

### Organisation

Set up your AWS organisation structure:

```bash theme={null}
fjall create organisation
# or use the alias
fjall create org
```

This creates:

* AWS Organization root
* Platform account for shared services
* SSO configuration
* Cost allocation tags
* Billing alerts

### Account

Set up standalone AWS account infrastructure:

```bash theme={null}
fjall create account
```

This creates:

* Monitoring and alerting
* CloudTrail audit logging
* ECR container registry
* OIDC connector for CI/CD

<Tip>
  For standalone use, create an account before applications. Organisation is an upgrade path, not a prerequisite.
</Tip>

### Application

Create a new application:

```bash theme={null}
fjall create application
# or
fjall create app
```

Choose from application types:

* **Standard**: Production-ready with 3 AZ, Fargate ECS, RDS
* **Lightweight**: Streamlined with Fargate Spot ECS, RDS
* **Resilient**: High-availability with 3 AZ, Aurora with readers, KMS encryption, RDS Proxy, 30-day backup
* **Enterprise**: Full-featured with 3-AZ, Aurora with readers, KMS encryption, VPC endpoints
* **Tinkerer**: Free-tier eligible experimental with 2 AZ, ECS on EC2 (t4g.micro), RDS
* **Custom**: Interactive selection of individual components

## Examples

### Create Organisation (Interactive)

```bash theme={null}
fjall create organisation
```

The interactive flow:

1. Prompts for organisation name, email, and regions
2. Opens your browser to deploy an OIDC CloudFormation stack in your AWS account
3. Polls for stack completion
4. Deploys the organisation using the OIDC connection

```bash theme={null}
? Organisation name: exampleorg
? Email address: aws@example.com
? Primary region: us-east-1
? Secondary regions: eu-west-1, ap-southeast-2
Opening browser to deploy OIDC stack...
Waiting for stack deployment to complete...
```

### Create Application (Interactive)

```bash theme={null}
fjall create app
```

Prompts:

```bash theme={null}
? Choose your starting point:
  ❯ Standard    Production-ready · Multi-AZ, Fargate ECS, RDS
    Lightweight Streamlined · Single-AZ, Instance-backed ECS, RDS
    Resilient   High-availability · Multi-AZ, Encrypted, Fargate ECS, Aurora
    Enterprise  Maximum capability · All features enabled, Aurora
    Tinkerer    Free experimental · Single-AZ, Free tier ECS, RDS
    Custom      Blank canvas · Build your way

? Name your application: app
? Include database: Yes
? Provide Dockerfile: No
```

### Non-Interactive Mode

Skip all prompts with flags:

```bash theme={null}
# Create organisation (uses current AWS profile credentials)
fjall create organisation \
  --name exampleorg \
  --email aws@example.com \
  --primary-region us-east-1 \
  --secondary-regions eu-west-1,ap-southeast-2 \
  --non-interactive

# Create application with tier
fjall create app \
  --name api \
  --type standard \
  --non-interactive

# Create application with the payload pattern
fjall create app \
  --name cms \
  --pattern payload \
  --non-interactive

# Create application restoring database from snapshot
fjall create app \
  --name web \
  --type standard \
  --database \
  --snapshot-identifier rds:my-production-snapshot \
  --snapshot-username postgres \
  --non-interactive
```

## Options

### Common Options

| Option              | Description      | Example                          |
| ------------------- | ---------------- | -------------------------------- |
| `--non-interactive` | Skip all prompts | `fjall create --non-interactive` |

### Organisation Options

| Option                                | Description                                                                                      | Example                                    |
| ------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `-n, --name <name>`                   | Organisation name                                                                                | `--name mycompany`                         |
| `--email <email>`                     | Root account email — use a monitored inbox; AWS root password recovery delivers reset links here | `--email aws@company.com`                  |
| `--primary-region <region>`           | Primary AWS region                                                                               | `--primary-region us-east-1`               |
| `--secondary-regions <regions>`       | Additional regions                                                                               | `--secondary-regions eu-west-1,ap-south-1` |
| `--disaster-recovery-region <region>` | Disaster recovery region                                                                         | `--disaster-recovery-region eu-west-1`     |
| `--security <tier>`                   | Governance profile (`foundation`, `compliance`, `hardened`)                                      | `--security compliance`                    |
| `--container <dir>`                   | Monorepo container directory between the repo root and `fjall/`                                  | `--container infra`                        |

### Account Options

| Option                      | Description                                                     | Example                      |
| --------------------------- | --------------------------------------------------------------- | ---------------------------- |
| `--primary-region <region>` | AWS region for account infrastructure                           | `--primary-region us-east-1` |
| `--container <dir>`         | Monorepo container directory between the repo root and `fjall/` | `--container infra`          |

### Application Options

| Option                           | Description                                                                                   | Example                                 |
| -------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------- |
| `-n, --name <name>`              | Application name                                                                              | `--name api-service`                    |
| `-t, --type <type>`              | Application tier (`tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`, `custom`) | `--type resilient`                      |
| `--pattern <pattern>`            | Application pattern (`payload` or `staticsite`)                                               | `--pattern payload`                     |
| `--tier <tier>`                  | Infrastructure tier for a pattern                                                             | `--tier standard`                       |
| `--pattern-tier <tier>`          | Alias for `--tier`                                                                            | `--pattern-tier standard`               |
| `--pattern-domain <domain>`      | Custom domain for the pattern                                                                 | `--pattern-domain app.example.com`      |
| `--source <dir>`                 | Static-site source directory — the build runs here and assets upload from here                | `--source ../..`                        |
| `--build-command <cmd>`          | Static-site build command                                                                     | `--build-command "npm run build"`       |
| `--output-dir <dir>`             | Static-site build output directory, relative to `--source`                                    | `--output-dir out`                      |
| `--routing <mode>`               | Static-site routing: `multipage` (clean URLs) or `spa` (index.html fallback)                  | `--routing multipage`                   |
| `--forms-to <email>`             | Static-site contact-form recipient (any address; requires `--pattern-domain`)                 | `--forms-to hello@example.com`          |
| `--cors-origin <origin>`         | Static-site forms CORS allow-origin (defaults to the site domain)                             | `--cors-origin https://example.com`     |
| `--services <json>`              | Service config as a JSON array                                                                | `--services '[{"name":"api"}]'`         |
| `--owner <owner>`                | Owner identifier                                                                              | `--owner backend-team`                  |
| `--network <preset>`             | Network preset (`none`, `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`)     | `--network standard`                    |
| `--database`                     | Include a database with the application                                                       | `--database`                            |
| `--snapshot-identifier <id>`     | RDS snapshot to restore the database from                                                     | `--snapshot-identifier rds:my-snapshot` |
| `--snapshot-username <user>`     | Master username from the snapshot                                                             | `--snapshot-username postgres`          |
| `--dockerfile [path]`            | Path to a custom Dockerfile                                                                   | `--dockerfile ./Dockerfile`             |
| `--container-port <port>`        | Container port                                                                                | `--container-port 8080`                 |
| `--template <template>`          | Starter template                                                                              | `--template api`                        |
| `--into <path>`                  | Scaffold into an existing repo instead of `./fjall/<name>`                                    | `--into ./repos/web`                    |
| `--container <dir>`              | Monorepo container directory (e.g. `apps`, `services`)                                        | `--container services`                  |
| `--target <name>`                | Override the active deployment target for this command                                        | `--target production-us-use1`           |
| `--dry-run`                      | Preview the scaffold without writing files or calling the API                                 | `--dry-run`                             |
| `--git`                          | Initialise a git repository                                                                   | `--git`                                 |
| `--github`                       | Create a GitHub repository                                                                    | `--github`                              |
| `--github-org <org>`             | GitHub organisation for the repository                                                        | `--github-org my-org`                   |
| `--repo-visibility <visibility>` | GitHub repo visibility (`public` or `private`)                                                | `--repo-visibility private`             |

<Warning>
  The `nextjs` pattern is not yet deployable. Recent CLI versions no longer offer it in the picker and refuse `--pattern nextjs` at create time; older versions accepted it and failed at deploy. Use `payload` for a Next.js-based app, or [`staticsite`](/patterns/static-site-pattern) for a pre-built static site.
</Warning>

## Application Types Explained

### Tinkerer

* **2 AZs** (VPC spans 2 AZs), no NAT gateways
* **ECS on EC2** (t4g.micro ARM Graviton), free-tier eligible
* **RDS Instance** (t4g.micro)
* Best for: Experimentation and learning

### Lightweight

* **2 AZs** (VPC spans 2 AZs), 1 NAT gateway
* **ECS Fargate Spot** (256 CPU, 512 MiB)
* **RDS Instance** (t4g.small)
* Best for: Small apps and side projects

### Standard

* **3 AZs**, 1 NAT gateway
* **ECS Fargate** (512 CPU, 1024 MiB)
* **RDS Instance** (t4g.large)
* Best for: Most production workloads

### Resilient

* **3 AZs**, 3 NAT gateways
* **Aurora** with readers, KMS encryption, RDS Proxy
* **30-day** backup retention
* Best for: High-availability applications

### Enterprise

* **3-AZ** deployment with 3 NAT Gateways
* **Aurora** database with 2 readers, KMS encryption
* **VPC endpoints**, S3 flow logs (365-day retention)
* Best for: Mission-critical applications

### Custom

* **Interactive selection** of components
* **Mix and match** resources
* **Full customisation**
* Best for: Specific requirements

## What Gets Created

### Account Structure (Standalone)

```
fjall/
├── account/
│   ├── infrastructure.ts
│   ├── package.json
│   └── cdk.json
└── fjall-config.json
```

### Organisation Structure

```
fjall/
├── organisation/
│   ├── infrastructure.ts
│   ├── package.json
│   └── cdk.json
├── platform/
│   ├── infrastructure.ts
│   ├── package.json
│   └── cdk.json
└── fjall-config.json
```

### Application Structure

```
fjall/
├── app/
│   ├── infrastructure.ts
│   ├── package.json
│   ├── cdk.json
│   └── Dockerfile (if applicable)
└── fjall-config.json
```

## Post-Creation Steps

### After Creating Organisation

1. **Deploy the organisation** (automatically cascades to platform and accounts):
   ```bash theme={null}
   fjall deploy organisation
   ```

### After Creating Application

1. **Review infrastructure code**:

   ```bash theme={null}
   cat fjall/app/infrastructure.ts
   ```

2. **Deploy the application**:

   ```bash theme={null}
   fjall deploy app
   ```

3. **Add more resources** (`--name` is required and PascalCase):
   ```bash theme={null}
   fjall add database --name AppDb --type Aurora --app app
   ```

## Best Practices

1. **Connect First**: Run `fjall connect` to establish an AWS connection before creating infrastructure
2. **Account First**: For standalone use, create an account (`fjall create account`) before applications. Organisation is an upgrade path, not a prerequisite.
3. **Naming Convention**: Names must start with a letter and can contain letters, numbers, and hyphens
4. **Region Selection**: Choose regions close to your users
5. **Type Selection**: Start with Tinkerer for learning, use Standard for production

## Troubleshooting

### Name Already Exists

If you see "Application already exists":

* Choose a different name
* Or remove existing: `rm -rf fjall/existing-app`

### OIDC Stack Deployment Fails

If the OIDC CloudFormation stack fails to deploy:

* Sign in to the correct AWS account in your browser
* Check that your account has permission to create IAM roles and CloudFormation stacks
* Retry with `fjall connect` to re-open the browser flow

### Connection Not Configured

If authentication fails:

* Run `fjall connect` to establish or verify your AWS connection
* If using SSO, check that your AWS SSO session is active

### Region Not Available

Some services are not available in all regions:

* Use `us-east-1` for full service availability
* Check AWS service availability by region
* Consider multi-region setup for resilience

<Note>
  The create command generates CDK TypeScript code. Modify the generated infrastructure.ts files to customise your setup further.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Connect AWS" icon="aws" href="/cli/connect">
    Establish an AWS connection before you create or deploy infrastructure.
  </Card>

  <Card title="Deploy" icon="rocket" href="/cli/deploy">
    Ship your application, account, or organisation to AWS.
  </Card>

  <Card title="Add resources" icon="plus" href="/cli/add">
    Add a database, storage, or compute to an application's infrastructure.ts.
  </Card>

  <Card title="List resources" icon="list" href="/cli/list">
    Inspect the resources declared in an application's infrastructure.ts.
  </Card>
</CardGroup>