chant emulator

Synopsis

chant emulator up     [--lexicon <name>] [--json]
chant emulator down   [--lexicon <name>] [--json]
chant emulator status [--lexicon <name>] [--json]

Description

chant emulator manages the local emulators of the lexicons your project configures, and reports the endpoint and environment that redirect tooling at them.

The Local Testing pages boot an emulator inside an Op, which tears it down again when the Op finishes. This command is the other shape: up leaves the emulator running so you can deploy to it, observe it with chant lifecycle diff --live, graph it with chant graph --live, and come back to it across several commands.

Every action is idempotent. up on an already-running emulator reports the existing endpoint rather than starting a second container.

Which lexicons have one

An emulator is a lexicon capability. Four lexicons declare five between them — a lexicon can ship more than one (chant #1345). Running the command in a project whose lexicons have none is not an error: it warns and exits 0, so a script that calls chant emulator up unconditionally still works.

Subcommands

emulator up

Boots each configured lexicon’s emulator container and waits for it to report healthy, then prints the endpoint.

chant emulator up

✓ aws: chant-floci up on http://localhost:4566
✓ azure: chant-floci-az up on http://localhost:4577
✓ gcp: chant-floci-gcp up on http://localhost:4588
✓ fly: chant-mudflaps up on http://localhost:4280
✓ fly: chant-spritzer up on http://localhost:4290

One line per emulator, not per lexicon: fly ships two, and --lexicon fly acts on both.

emulator down

Stops and removes the containers.

chant emulator down

emulator status

Reports whether each emulator is running, without starting or stopping anything. A container that is not running reports down with an empty endpoint.

chant emulator status

aws: chant-floci — up on http://localhost:4566

Flags

Flag	Description
--lexicon <name>	Act on one lexicon’s emulator instead of all of them. A lexicon with no emulator, or one this project does not configure, warns and exits 0.
--json	Emit the machine-readable report on stdout instead of the human summary.

--json

The report is the contract other tools consume — behold’s serve --local uses it to point itself at a running emulator.

chant emulator up --json

{
  "emulators": [
    {
      "lexicon": "aws",
      "name": "chant-floci",
      "endpoint": "http://localhost:4566",
      "env": {
        "AWS_ENDPOINT_URL": "http://localhost:4566",
        "AWS_ACCESS_KEY_ID": "test",
        "AWS_SECRET_ACCESS_KEY": "test",
        "AWS_REGION": "us-east-1"
      }
    }
  ]
}

env is the point of the report: exporting those variables is what makes the AWS SDK, chant lifecycle --live, and a triggered Op talk to the emulator rather than the real account.

eval "$(chant emulator up --json | jq -r '.emulators[].env | to_entries[] | "export \(.key)=\(.value)"')"
chant lifecycle diff local --live

down and a stopped status report an empty endpoint and an empty env, so a consumer can tell “not running” from “running here” without parsing prose. With --json, a project whose lexicons have no emulator reports {"emulators":[]}.

Declaring an endpoint instead

For an environment you use repeatedly, declaring its endpoint in chant.config.ts under environments means --live --env <name> finds the emulator without exporting anything. This command is for the ad-hoc case, and for tools that need the endpoint programmatically.

The emulators

Lexicon	Container	Image	Port	Health check	Endpoint var
aws	chant-floci	floci/floci:1.5.34	4566	/_localstack/health, waiting on cloudformation	AWS_ENDPOINT_URL
azure	chant-floci-az	floci/floci-az:0.10.0	4577	/_floci/health	AZURE_ENDPOINT_URL
gcp	chant-floci-gcp	floci/floci-gcp:0.5.0	4588	/_floci-gcp/health	—
fly	chant-mudflaps	ghcr.io/intentius/mudflaps:0.4.1	4280	/_mudflaps/health	FLY_FLAPS_BASE_URL
fly	chant-spritzer	ghcr.io/intentius/spritzer:0.4.1	4290	/_spritzer/health	SPRITES_BASE_URL

gcp has no endpoint variable because gcpApply takes the endpoint as an explicit argument rather than reading one — chant emulator up --json still reports the endpoint, there is just nothing to export.

Every image is pinned rather than tracking :latest, so a local suite that passes today does not fail tomorrow because an image moved. A weekly workflow reports how far behind each pin is; the bump is a human decision, made when a consuming test needs the newer emulator.

Requires Docker. If Docker is missing or not running, status reports the emulator as down rather than failing.

Exit Codes

Code	Meaning
0	The action completed, including the case where no configured lexicon has an emulator
1	No subcommand, or one that is not up, down, or status

See Also

• Local Testing — deploying chant’s real output to an emulator, per cloud
• chant lifecycle — observing a running emulator with --live
• Config File — binding an endpoint to a named environment