Layout CLI

The Layout CLI signs in to your developer account. In sandbox it does the whole build: create an application and a key, call any endpoint, forward webhook events to your machine, fire test events, and run a whole test order. In production it reads: live events, deliveries and key details. It never changes an approved application's production settings, and never moves money. Every command takes --json, so a coding agent can drive it.

Install

Install it from npm. It needs Node 20 or later, and the command is layout.

npm i -g @layoutplatforms/cli

Or run it once without installing: npx @layoutplatforms/cli login.

Sign in

layout login

It prints a code like BCDF-GHJK and opens the console. Check that the code matches your terminal, then choose Approve. The code lasts 10 minutes. The session lasts 30 days, and layout logout ends it. The console's CLI page lists every signed-in CLI, each with Revoke.

The token is kept in the macOS Keychain or the Linux Secret Service (secret-tool). With neither, it goes in ~/.config/layout/credentials.json with mode 0600, and the CLI warns you. LAYOUT_CREDENTIAL_STORE (keychain, secret-tool or file) picks the store.

CI tokens

For CI, a container or a coding agent, create a token on the console's CLI page (New token) and set it as LAYOUT_CLI_TOKEN. Every command then runs without layout login.

export LAYOUT_CLI_TOKEN=lcli_...
layout init --name "My app"

• Creating one needs a console sign-in from the last 15 minutes. It is shown once, and Layout keeps only a hash of it.
• It lasts 30 days, 90 days (the default) or a year, and the CLI page lists it with Revoke. Signing out everywhere revokes it too.
• It is sandbox only. Production reads still need layout login --live.
• When it is set it wins over a keychain session. It is only ever sent to https://api.layout.link, and the CLI never writes it to disk.

LAYOUT_API_BASE points the CLI at another API. The default is https://api.layout.link. A token is only ever sent to the API that issued it.

Commands

Destructive commands do nothing without --yes. webhooks add and webhooks remove work only while the application is not approved, and exit 4 after; the console changes endpoints at any time. An endpoint receives sandbox events, live events or both, and the default is both, so one added under review without --environment sandbox also receives live events once the application is approved. webhooks add turns the endpoint on when it answers endpoint.verification with a 2xx. Otherwise it is added but off, and the command exits 1 with endpoint_not_verified and the subscriptionId on stderr, or 6 if Layout was rate limited and sent no verification. The production signing secret is shown only in the console.

Global flags

NO_COLOR, or output that is not a terminal, turns colour off. Once a day the CLI checks npm and tells you on stderr when a newer version is out, except with --json. CI or LAYOUT_NO_UPDATE_CHECK turns that off.

Choosing an application

Commands that act on one application take --app. If the account has exactly one application, it is used. With several, the CLI lists them and exits with code 2. With --json, the error carries apps, each with id, name and status. From CLI 0.4.2, a name shared by several applications also exits with code 2 and lists them, and a name no application has exits with code 5. With none, it exits with code 5, except init, which exits with code 2 and asks for --name.

Forward events with listen

layout listen --forward-to http://localhost:3000/layout/webhooks

listen reads the application's sandbox event feed every 2 seconds and POSTs each event to --forward-to. Each request is signed like a real webhook, with a secret made for this run and printed when it starts (whsec_cli_...), or with --secret <whsec>, at least 16 characters, so your handler keeps one secret across runs. Pair it with layout check --forward-to <url> --secret <the same secret>.

Verify it with the same code as a real webhook, using the printed secret. See Webhooks. Without --secret, the secret is new on every run and is not your application's sandbox signing secret, so give your server the one this run printed (with --json, the secret of the first line) each time you start listen. listen runs until you stop it: a coding agent should start it in the background.

• Events arrive in order. An event is retried with backoff until your server answers 2xx, so nothing is skipped.
• The position is saved after each event, separately for sandbox and production. A restart or a dropped connection resumes after the last event forwarded and never forwards one twice.
• It starts from now, not from history, unless you pass --from-start or a saved position exists.
• No webhook endpoint is needed in sandbox. While listen runs, the sandbox feed records your application's sandbox events even when it has no enabled endpoint; they are forwarded to you and sent nowhere else. Events from layout trigger are included.
• If Layout cannot start recording for this run, listen says why on stderr and asks again every 10 seconds; recordsWithoutEndpoint on the first line is false until it does. Ctrl-C stops it at once and exits 130.
• With --live, the feed holds only the production events an enabled endpoint subscribes to. The CLI warns you when the application has no enabled endpoint.
• --events forwards only the events you name. The ones it skips still move the saved position, so a later run without --events does not send them.

With --json, the first line is {"event":"listening","app","environment","forwardTo","secret","resumed","recordsWithoutEndpoint"}, then one line per forwarded event:

{"cursor":"...","event":"order.placed","eventId":"evt_...","status":200,"forwardedAt":"2026-10-02T17:04:11Z"}

Fire a test event

layout trigger order.unconfirmed --order ord_7c21

trigger does what POST /v1/sandbox/webhooks/fire does: any event except order.needs_approval, and --order makes it describe one of your sandbox orders. A triggered order.updated carries ready_eta and fulfillment: the order’s own with --order, placeholders otherwise. It goes to every enabled endpoint subscribed to the event, and to a running layout listen. 1,000 a day for each developer account, and 30 a minute. See Fire a test webhook.

Call the API

layout api get /v1/whoami
layout api post /v1/users -d firstName=Dana -d phone=+15005550123
layout api get "/v1/places?query=coffee" --token lgb_...
layout api post /v1/carts --token lgb_... --data @cart.json

Places, menus, item images and carts act for one person, so they take that person's build grant or OAuth access token in --token. Sent with only your key, they answer 403 wrong_credential. See Calling as a person.

api sends one request to the Layout API and prints the JSON answer on stdout, with the status and X-Request-Id on stderr. With --json it prints one object on stdout instead: {"status","requestId","replayed","body"}. The path can leave out /v1. It exits 0 for a 2xx and otherwise with the exit code for the status.

Which key it uses:

• --token, when you give one.
• Otherwise LAYOUT_SECRET_KEY, when it is set. This works without layout login, as in CI.
• Otherwise the application's sandbox key. After layout login, the CLI reads it once and keeps it in the same keychain as its token, and reads it again if it was rotated. Logging out deletes it. With LAYOUT_CLI_TOKEN, it reads the key on every run and stores nothing. Each read counts against your developer account's 40 key reads a day, so in CI also set LAYOUT_SECRET_KEY.

Before a POST or DELETE, the CLI asks GET /v1/whoami whether that credential is sandbox, and sends nothing if Layout says production or cannot say. A live secret works only with --live, and only for GET.

Run a test order

layout test-order --place test_place_placed

test-order runs a whole sandbox order and prints each step:

1. Uses LAYOUT_SECRET_KEY when it is set, so it runs in CI without signing in. A live key there is refused with exit code 2. Without it, it uses the application's sandbox key from the keychain, as api does: the first run reveals that key once, from your signed-in session, and keeps it in the keychain for later runs.
2. Provisions a sandbox test user with a +1 500 555 number and verifies it with 000000.
3. Mints a build grant and builds a cart, at test_place_placed unless you name another place. At a real restaurant it first reads the menu Layout holds and orders its first item.
4. Waits for the cart to be ready, confirms it (simulated), and waits for the order's outcome.

From CLI 0.5.0, --place takes a placeId from a sandbox places search, with --simulate for the ending (placed by default) and --latency for the wait (instant by default). It exits 0 when the order ends as --simulate says: failed for failed, card_declined and closed, unconfirmed for unconfirmed, and placed for the rest. A test restaurant takes neither flag. An id starting test_place_ that no test restaurant carries exits with code 2. From CLI 0.4.2 it also runs test_place_needs_choices (it answers the required choice), test_place_needs_location (it builds at the first candidate), test_place_pickup_later (it waits for the pickup time) and test_place_delivery_far. It exits 0 only when the order reaches the outcome the test restaurant scripts:

• placed for test_place_placed, test_place_carted, test_place_branch_north, test_place_branch_south, test_place_challenge, test_place_slow, test_place_price_changed, test_place_needs_choices, test_place_needs_location, test_place_pickup_later and test_place_delivery_far. A price_changed refusal is shown as its own step with the old and new totals, and the confirm shows the total it confirmed.
• failed for test_place_failed, and for test_place_closed, whose cart fails before any confirm. From CLI 0.4.3, also failed for test_place_card_declined_confirm, whose confirm answers 402 card_declined.
• unconfirmed for test_place_unconfirmed.
• From CLI 0.3.1, placed for test_place_code: when the confirm answers code_required, the CLI sends the sandbox code 000000. Earlier versions refuse test_place_code with exit code 2. layout --version prints yours.

{"app":"lyt_app_...","place":"test_place_placed","steps":[{"step":"Read the sandbox key","status":"ok","detail":"..."}],"order":{"id":"ord_7c21","status":"placed","confirmedTotalMinor":1019},"ok":true}

Check your integration

layout check --forward-to http://localhost:3000/webhooks/layout

From CLI 0.5.0, check grades your integration from the last 24 hours of your application’s sandbox, and prints each check with what to do when it does not pass. --since grades a shorter window instead, such as --since 30m or --since 2h, up to 24h.

Only orders your application confirmed count toward an ending. Carts the CLI built are left out: every POST that layout api and layout test-order send carries an Idempotency-Key starting cli- unless you give one, and check leaves out every test person a cart with such a key was built for. So use a different test person for your application’s own carts than for CLI runs, and never start your own idempotency keys with cli-.

With --forward-to, it also sends your handler a test order.placed event four ways. The URL is https, or http on localhost. They test how your handler checks signatures and that it answers a repeat with a 2xx. Each carries "test": true and its own event_id, except the repeat, so a handler that skips test events must still answer them as below.

It signs with your application’s sandbox signing secret. When your handler verifies with the secret layout listen used, pass that one as --secret. Without --forward-to, the check Your webhook handler fails. An integration that reads GET /v1/orders instead of taking webhooks passes --no-webhooks, which skips it.

check exits 0 when nothing failed and 1 otherwise, so an agent can run it until it passes.

$ layout check --forward-to http://localhost:3000/webhooks/layout --json
{"app":"lyt_app_...","windowHours":24,"checks":[{"name":"Builds a cart","result":"pass"},...,{"name":"Reaches unconfirmed","result":"fail","fix":"Build with \"simulate\": \"unconfirmed\", confirm it, and tell the person to check with the restaurant."},...,{"name":"Does not build again after unconfirmed","result":"skip","fix":"Runs once an order has ended unconfirmed."},...],"passed":14,"failed":1,"skipped":1,"ok":false}

JSON output

With --json, every command prints one JSON object on stdout. Two print more than one line: login prints a code line and then a signed-in line, and listen prints a listening line and then one line per event. An error is {"error":{"code","message"}} on stderr. api is the exception: it prints the answer of any status on stdout as {"status","requestId","replayed","body"}, and only the CLI's own errors go to stderr. When test-order or init fails partway, stdout also gets the steps so far, with "ok":false.

{"event":"code","userCode":"BCDF-GHJK","verificationUri":"https://console.layout.link/cli","verificationUriComplete":"https://console.layout.link/cli?code=BCDF-GHJK","expiresIn":600,"live":false}
{"event":"signed_in","account":{...},"session":{...}}

$ layout whoami --json
{"kind":"cli","environment":"sandbox","account":{"id":"...","name":"Acme","status":"active"},"session":{"id":"...","kind":"device","deviceName":"dana-mbp","createdAt":"...","expiresAt":"...","liveUntil":null},"capabilities":["whoami","listen:sandbox","apps:read","apps:create","keys:sandbox","webhooks:read","webhooks:sandbox","events:sandbox","trigger:sandbox","usage:read","deliveries:sandbox","live_access:request","refusals:read","check:sandbox"]}

$ layout apps create "Acme Ordering" --json
{"app":{"id":"lyt_app_...","name":"Acme Ordering","status":"pending","createdAt":"..."},"sandboxKey":{"clientId":"lp_test_...","secret":"sk_test_..."}}

$ layout keys create --replace --json
{"app":"lyt_app_...","environment":"sandbox","clientId":"lp_test_...","secret":"sk_test_...","replaced":true,"previousSecretExpiresAt":"2026-10-23T17:00:00.000Z"}

Unknown flags and places

From CLI 0.4.3, a flag or a test place the CLI does not know ends with This is @layoutplatforms/cli 0.4.3; newer versions may support this: npm i -g @layoutplatforms/cli, since a newer CLI may.

Exit codes

Retries

Network errors, 502, 503 and 504 are retried with backoff, up to four tries, and a read also retries 429. Every create, revoke, trigger and review request, and every POST from api, carries an Idempotency-Key, so a retry returns the first answer instead of doing it twice.

Production

layout login --live
layout listen --live --forward-to http://localhost:3000/layout/webhooks
layout deliveries --live

keys list --live, webhooks list --live and refusals --live need no layout login --live. listen and deliveries still do. From CLI 0.4.3.

With production access, a session can read production as well as build in sandbox. The console marks the request as production and asks you to sign in again if your last sign-in was more than 15 minutes ago, the same check as showing a live secret. The access lasts 12 hours from sign-in. After that, --live exits 4 with live_session_required and sandbox keeps working for the rest of the 30 days. The application must be approved for production, or it exits 4 with not_approved.

Layout enforces the left column on its side: a CLI token reaches only the read routes in production, and only while its access lasts.

Security

• Layout stores the token hashed and records every action it takes in your account's audit trail.
• Only a signed-in console user can approve a sign-in code, and the token belongs to that account. Production access also needs a sign-in from the last 15 minutes.
• The CLI keeps only a sandbox key, never a live secret. If a computer is lost, revoke its session and replace the sandbox key.
• With --live, listen forwards only to an https URL or to this computer.