Skip to main content
fjall dev manages ephemeral dev-environment slots. Each slot is one branch’s preview environment, running on a shared per-application substrate (a database, a load balancer and dev DNS).
  • Signed in. Every dev subcommand authenticates first. Run fjall login.
  • An application registered with Fjall. The <app> argument resolves to an application in your organisation.
  • A dev substrate in ready state for that application. fjall dev up reads the substrate to learn which ECR repository to push to. A substrate that is creating, in error, or absent fails the command before any build starts.
  • Docker running locally, plus a Dockerfile. fjall dev up builds the branch image on your machine and pushes it.
  • A git checkout, or pass --branch <name>. Outside a git repository with no flag, the command stops and asks for --branch.

​
Manage dev slots

Bare fjall dev and bare fjall dev substrate print help.

​
What Happens

​
fjall dev up

  1. Reads the application’s dev substrate. The substrate must report ready with an account, a region and a slot repository, otherwise the command fails with the substrate’s current status.
  2. Mints short-lived dev-deploy credentials for the substrate’s AWS account.
  3. Probes the slot ECR repository before building, so a substrate torn down outside Fjall fails immediately instead of minutes later at the push.
  4. Builds the image from --context using --dockerfile, then pushes it to the slot repository.
  5. Creates the slot record with the resulting image tag, container port, health-check path, migration command, seed command and environment variables.
  6. Polls the slot until it becomes active, then prints its URL.
The image tag is derived from the branch name with a 7-character commit sha appended, for example feature-search-a1b2c3d. Characters outside [a-zA-Z0-9._-] become hyphens, a leading . or - is stripped, and the tag is bounded to 128 characters with the sha suffix preserved. If the build context holds a prisma/migrations directory, fjall dev up derives the expected schema-version variables from the latest migration and reports which keys it added. Your own --env values win on the same key.

​
Warnings you may see

​
Waiting and slot status

Slot statuses are creating, active, idle, waking, destroying, destroyed and error. active ends the wait successfully. error and a mid-flight teardown end it as a failure. Any other status keeps polling. fjall dev up polls every 5 seconds for up to 30 minutes and tolerates 3 consecutive network failures. After 60 seconds it notes that an idle substrate resumes its paused database on demand and a cold first boot can take around 10 minutes. After 15 minutes it reminds you that provisioning continues server-side, so you can stop waiting and run fjall dev list <app> later. A timeout reports the wait budget, not a lost slot.

​
fjall dev list

Prints one row per slot with STATUS, BRANCH, URL and ID, followed by a count. It queries the Fjall control plane only and changes nothing. A Fjall server that predates dev environments produces a notice and exit code 0 rather than an error.

​
fjall dev down

Resolves the branch from --branch or the current git branch, finds that branch’s live slot and destroys it. No matching slot is treated as success with a notice, so repeat runs are safe.

​
fjall dev substrate down

Destroys the shared substrate behind every slot for the application. It refuses while slots are still live, and points you at fjall dev down or --force. On success it lists the residual AWS resources that survive the teardown, with a cleanup hint for each. The teardown poll budget is 45 minutes.
fjall dev substrate down --force tears down live dev slots along with the substrate. Every slot database dies with the shared cluster, including your teammates’ slots.

​
Dry runs and agent mode

There is no dry-run flag on fjall dev. fjall dev list is the read-only surface, so check it before a teardown. With --agent, each subcommand prints a single JSON result instead of streaming progress. Git-hygiene warnings from dev up ride the result object. fjall dev list --agent --fields selects from id, slotKey, branch, status and host, and an invalid selection fails before the authentication round-trip.

​
Options

​
fjall dev up <app>

Each --env token splits on the first =, so a value containing = survives intact. --env FLAG= sets an empty value. A bare KEY with no = fails the whole command, and no slot is created.

​
fjall dev list <app>

Takes the shared flags only.

​
fjall dev down <app>

​
fjall dev substrate down <app>

--yes and --force are separate on purpose. --yes confirms a plain teardown, which still refuses while slots are live. --force takes those slots down with the substrate. A non-TTY session, or --non-interactive, never auto-accepts, so scripted teardowns pass --yes deliberately.

​
Shared flags

Available on dev up, dev list, dev down and dev substrate down. The dev and dev substrate group commands themselves accept --non-interactive and -v, --verbose.

​
Next Steps

fjall deploy

Promote a branch to a real environment once the slot looks right.

fjall secrets

Store credentials properly instead of passing them as slot --env values.

fjall build

Build and push application images outside the dev-slot flow.

Agent mode

Drive fjall dev from an AI agent with JSON output and field selection.