Docs/CLI

Nexlayer CLI

One command builds your whole app on Nexlayer, deploys it and proves it works. Every answer ends with the one next step, so you, or your coding agent, always know what to do.

Hand this to your coding agent

Paste this into Claude Code, Codex, Cursor or any agent that runs commands. Agents that ask for text/markdown get this page as Markdown.

Install the Nexlayer CLI and ship this app:

1. curl -fsSL https://nexlayer.com/cli/install.sh | bash
2. nexlayer login   (I'll approve it in my browser)
3. nexlayer ship --json

Follow the "next" field in every answer. If the exit code is 3, stop and ask me. Never put secrets in the chat or the repo.
Reference: https://nexlayer.com/docs/cli

Install

One line, on macOS or Linux. On Windows, download the .exe from the CLI page.

bash
curl -fsSL https://nexlayer.com/cli/install.sh | bash

Then check the machine is ready. doctor changes nothing and says what to fix.

bash
nexlayer doctor
Install only from nexlayer.com/cli. The npm packages named nexlayer and nexlayer-cli are not Nexlayer's.

Quickstart

  1. 1

    Sign in, once per machine

    Your browser opens Nexlayer's approval screen. Approve it and you're done.

    bash
    nexlayer login
  2. 2

    Ship from your project folder

    Builds every part on Nexlayer (no Docker needed), deploys the app and checks it works. --check names routes that must answer.

    bash
    cd my-app
    nexlayer ship --check /api/health
  3. 3

    See what's live

    Reads the version from the running app and tells you whether your checkout is up to date.

    bash
    nexlayer status
  4. 4

    If it isn't ✓

    ship already did this for you. Run it again any time for the cause and the one next step.

    bash
    nexlayer why
No nexlayer.yaml yet? ship plans your repo and writes one, or shows how to write it. Want to see Nexlayer work first? nexlayer new fastapi deploys a full-stack template from prebuilt images, no build.

How ship works

ship runs the same five steps, in the same order, every time. Run nexlayer ship --plan to see them for your repo first. It reads local files only and sends nothing.

1checknexlayer.yaml with Nexlayer's validator
2buildevery part on Nexlayer from the files on disk
3deploythe whole app
4verifythe live app works, plus your --check routes
5diagnoseonly if it isn't ✓: every part's logs → one cause

Image tags are the git commit. Uncommitted changes ship too, as their own image (<commit>-<time>), so a fix never reuses the tag of the image it replaces. Commit once it's ✓ Working.

The agent contract

The CLI is built to be driven by an AI agent. Three things never change.

1. One result shape

With --json, every command, failures included, prints one line that starts the same way.

json
{"kind":"ship","status":"working","exit_code":0,"next":"You can tell the person it's live.","app":"my-app","url":"https://my-app.cloud.nexlayer.ai"}

So … | jq -r .next works after any command. When ship isn't ✓, the result names the step it stopped at (failed_step) and the one command that redoes just that step (retry).

2. Exit codes that mean one thing

See Exit codes.

3. Every answer ends with Next

The single thing to do, in plain words. Secrets never appear: keys show by name only, and when one is missing the CLI sends the person a link to add it in Nexlayer, never the chat.

Flags for agents

--jsonOne line, always {kind, status, exit_code, next, …}.
--eventsship and new: one JSON line per step, then the result (kind "result").
--out <file>Big answers go to a file with a short summary on screen. Grep the file.
--planship: the steps, parts and image tag, from local files only.

Exit codes

CodeMeaningWhat the agent does
0WorkingTell the person it's live.
1Deployed but not workingRead cause and next, fix it, ship again.
2Couldn't confirmName the routes that matter with --check, then verify again.
3Needs the personStop and ask: a key, a card, Docker, sign-in. Never work around it.
4FailedFix what detail says, ship again.
5Nexlayer had a problemWait, then retry. Change nothing.
64The command line was wrongSee nexlayer help --json.

Commands

Every command takes --json and --out. nexlayer help --json prints this whole tree, machine-readable.

Workflows

Run several steps for you and change the app. --plan shows the steps first.

nexlayer shipchanges the app

Check nexlayer.yaml → build every part on Nexlayer → deploy → verify → if it isn't ✓, read every part's logs and name the cause.

  • --plan show the steps, parts and image tag from local files only; nothing is sent
  • --check /api/health a route that must work (repeat it; remembered in .nexlayer/cli.json)
  • --reason "add search" one line on why, shown in your dashboard
  • --events one JSON line per step, then the result
  • --docker build with Docker on this machine instead of on Nexlayer
  • --wait 120 seconds to let the app settle before checking
  • --timeout 30m stop waiting (exit 2: it may still finish on Nexlayer)
nexlayer new [template]changes the app

Deploy a ready-made template from prebuilt images, then verify. With no template, lists the ways to start.

Look

Change nothing. Use them to check, or to redo the one step a workflow stopped at.

nexlayer status [app]changes nothing

Which version is live, read from the running images, and whether this checkout is up to date. Plus the app's parts, keys (names only) and the next step.

  • --json up_to_date is true, false or null (null means it couldn't tell)
nexlayer why [app]changes nothing

What's wrong and the one thing to do next: verify + the routes that must work + every part's logs.

nexlayer verify [app]changes nothing

Check that the deployed app works.

nexlayer logs [app]changes nothing

Recent logs from every part of the app.

nexlayer doctorchanges nothing

Is this machine ready: sign-in, Nexlayer reachable, Docker, repo, nexlayer.yaml.

Build

Turn a folder into an image without touching the running app.

nexlayer build [dir]changes nothing

Build a folder on Nexlayer: no git, no Docker, no registry login. Uploads only what changed, never files that look like credentials, and returns the image.

  • --dry-run show what would be sent

Sign-in, secrets and keys

Values come in by prompt, pipe or --from-env. Never as an argument, never printed to an agent.

nexlayer loginchanges nothing

Approve this agent in your browser, once per machine.

  • --check am I signed in?
  • --start / --finish sign in where no browser can open
  • --import sign in from a credentials bundle
nexlayer logoutchanges nothing

Forget this machine's saved sign-in.

nexlayer vault set|get|list|delete|statuschanges nothing

Deploy secrets in this machine's keychain. ship fills ${NAME} references from it at deploy.

nexlayer keys create|list|revoke|showchanges the app

API keys on your account. create stores the new key in the vault and never prints it. revoke needs --yes.

nexlayer credentials exportchanges nothing

For a person at a terminal: a bundle to sign in somewhere that can't open a browser.

Operate

The rest of the common jobs.

nexlayer debug describe|restart|scalechanges the app

Look inside a running part of the app, restart it or scale it.

nexlayer domainschanges the app

Custom domains: guide, add, check, verify.

nexlayer billingdepends on the tool

Credits, coupons, plan and referral.

nexlayer deletechanges the app

Remove a deployed app. Ask the person first, then pass --yes.

nexlayer feedbackchanges nothing

Tell Nexlayer what worked or didn't.

Any Nexlayer tool

Everything the Nexlayer MCP can do, from the command line.

nexlayer tools search <words>changes nothing

Find a tool. tools show <tool> prints its inputs.

nexlayer call <tool> -a name=valuedepends on the tool

Run any tool (or --args '{json}'). Tools marked ask the person first need --yes.

nexlayer help --jsonchanges nothing

The whole command tree: every command, its type (workflow or step), what it changes, and a workflow's steps.

Secrets

nexlayer.yaml holds ${NAME} references, never values. Store the value once in your machine's keychain and ship fills it in at deploy.

bash
nexlayer vault set STRIPE_KEY --from-env STRIPE_KEY
# ✓ Stored STRIPE_KEY (32 characters) in the keychain.

nexlayer ship
# → filled 1 key(s) from the vault or environment (values not shown)

Values come in by a hidden prompt, a pipe or --from-env, never as an argument. vault list shows names only. vault get --reveal prints a value, and only on a terminal a person is using.

Sign in without a browser

For web agents, sandboxes, SSH sessions and CI.

A person can approve on another device

nexlayer login --start prints a link. The person approves on any device and copies the code Nexlayer shows. Then nexlayer login --finish '<code>'.

CI or a machine with no person

Set NEXLAYER_API_KEY to a key made in Nexlayer. Keys made from a signed-in session can push images.

Move an existing sign-in

A person at a terminal runs nexlayer credentials export. Pass the bundle as NEXLAYER_CREDENTIALS, or use nexlayer login --import.

Files in your repo

nexlayer.yaml

Your agent, or Nexlayer's plan

The app: its parts, images, ports, routes and ${KEY} references. Format: nexlayer call get_schema.

.nexlayer/pipeline.yaml

Nexlayer's plan (optional)

Which Dockerfile builds which part. Without it, ship uses <part>/Dockerfile or ./Dockerfile.

.nexlayer/cli.json

ship

How to ship this repo and the routes that must work. Commit it so your next agent session knows without being told.

Configuration

NEXLAYER_API_KEY

Default: —

Sign in with an API key (CI, machines without a browser) instead of nexlayer login.

NEXLAYER_CREDENTIALS

Default: —

A bundle from credentials export: the sign-in for a web agent or CI.

NEXLAYER_ACCESS_TOKEN

Default: —

A ready-made access token, for systems that already hold the person's token.

AI_AGENT

Default: detected

Names the agent running the CLI so the person sees who deployed. Set it in a sandbox where it can't be detected.

NEXLAYER_VAULT

Default: auto

file forces the file vault (CI, containers) · keyring never falls back from the OS keychain · none never stores anything.

NEXLAYER_DEBUG=1

Default: off

Log every call to Nexlayer on stderr: tool and argument names, never values.

--server / NEXLAYER_MCP_URL

Default: https://mcp.nexlayer.ai/api/mcp

Which Nexlayer MCP to use.

NEXLAYER_BUILD_URL

Default: https://pipeline.nexlayer.com

The build service build and ship upload to.

Security

  • Sign-in is OAuth 2.1 with PKCE. You approve the agent once, on Nexlayer's own approval screen. The token is stored for your user only.
  • Credentials live in the OS keychain. macOS Keychain, Windows Credential Manager or Linux Secret Service. A file only you can read is used only when none exists; vault status says which.
  • No credential is ever printed to an agent. Tool output is redacted, and files that look like credentials are never uploaded by build.
  • Destructive actions need the person. Deleting an app or managing API keys is marked ask the person first and needs --yes.
  • The CLI never invents an answer. If Nexlayer didn't answer, the result is exit 5 with change nothing. Never a guess.

Troubleshooting

Exit 3: it stopped and asked for me

Something only you can do: add a key in Nexlayer, add a card, sign in. The answer's next field says which. Do it, then run the same command again.

Exit 5: Nexlayer had a problem

It's on Nexlayer's side, not your app. Wait two minutes and run the command again. Change nothing in the meantime.

A ship was cut off

Run nexlayer status before shipping again. It reads what's actually live and tells you whether this checkout is newer, older or the same.

up_to_date is null

The CLI couldn't tell: a deploy still going out, an image deployed some other way, or a version it couldn't read. It's not yes and not no. Run status again in a minute.

Is this machine ready?

nexlayer doctor checks sign-in, that Nexlayer is reachable, Docker, the repo and nexlayer.yaml, and says what to fix.

I want to see every call

Set NEXLAYER_DEBUG=1. Every call to Nexlayer is logged on stderr with tool and argument names, never values.