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/cliInstall
One line, on macOS or Linux. On Windows, download the .exe from the CLI page.
curl -fsSL https://nexlayer.com/cli/install.sh | bashThen check the machine is ready. doctor changes nothing and says what to fix.
nexlayer doctornexlayer.com/cli. The npm packages named nexlayer and nexlayer-cli are not Nexlayer's.Quickstart
- 1
Sign in, once per machine
Your browser opens Nexlayer's approval screen. Approve it and you're done.
bashnexlayer login - 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.
bashcd my-app nexlayer ship --check /api/health - 3
See what's live
Reads the version from the running app and tells you whether your checkout is up to date.
bashnexlayer status - 4
If it isn't ✓
ship already did this for you. Run it again any time for the cause and the one next step.
bashnexlayer why
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.
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.
{"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
Exit codes
| Code | Meaning | What the agent does |
|---|---|---|
| 0 | Working | Tell the person it's live. |
| 1 | Deployed but not working | Read cause and next, fix it, ship again. |
| 2 | Couldn't confirm | Name the routes that matter with --check, then verify again. |
| 3 | Needs the person | Stop and ask: a key, a card, Docker, sign-in. Never work around it. |
| 4 | Failed | Fix what detail says, ship again. |
| 5 | Nexlayer had a problem | Wait, then retry. Change nothing. |
| 64 | The command line was wrong | See 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 appCheck nexlayer.yaml → build every part on Nexlayer → deploy → verify → if it isn't ✓, read every part's logs and name the cause.
--planshow the steps, parts and image tag from local files only; nothing is sent--check /api/healtha route that must work (repeat it; remembered in .nexlayer/cli.json)--reason "add search"one line on why, shown in your dashboard--eventsone JSON line per step, then the result--dockerbuild with Docker on this machine instead of on Nexlayer--wait 120seconds to let the app settle before checking--timeout 30mstop waiting (exit 2: it may still finish on Nexlayer)
nexlayer new [template]changes the appDeploy 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 nothingWhich 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.
--jsonup_to_date is true, false or null (null means it couldn't tell)
nexlayer why [app]changes nothingWhat's wrong and the one thing to do next: verify + the routes that must work + every part's logs.
nexlayer verify [app]changes nothingCheck that the deployed app works.
nexlayer logs [app]changes nothingRecent logs from every part of the app.
nexlayer doctorchanges nothingIs 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 nothingBuild 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-runshow 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 nothingApprove this agent in your browser, once per machine.
--checkam I signed in?--start / --finishsign in where no browser can open--importsign in from a credentials bundle
nexlayer logoutchanges nothingForget this machine's saved sign-in.
nexlayer vault set|get|list|delete|statuschanges nothingDeploy secrets in this machine's keychain. ship fills ${NAME} references from it at deploy.
nexlayer keys create|list|revoke|showchanges the appAPI keys on your account. create stores the new key in the vault and never prints it. revoke needs --yes.
nexlayer credentials exportchanges nothingFor 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 appLook inside a running part of the app, restart it or scale it.
nexlayer domainschanges the appCustom domains: guide, add, check, verify.
nexlayer billingdepends on the toolCredits, coupons, plan and referral.
nexlayer deletechanges the appRemove a deployed app. Ask the person first, then pass --yes.
nexlayer feedbackchanges nothingTell Nexlayer what worked or didn't.
Any Nexlayer tool
Everything the Nexlayer MCP can do, from the command line.
nexlayer tools search <words>changes nothingFind a tool. tools show <tool> prints its inputs.
nexlayer call <tool> -a name=valuedepends on the toolRun any tool (or --args '{json}'). Tools marked ask the person first need --yes.
nexlayer help --jsonchanges nothingThe 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.
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.yamlYour agent, or Nexlayer's plan
The app: its parts, images, ports, routes and ${KEY} references. Format: nexlayer call get_schema.
.nexlayer/pipeline.yamlNexlayer's plan (optional)
Which Dockerfile builds which part. Without it, ship uses <part>/Dockerfile or ./Dockerfile.
.nexlayer/cli.jsonship
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_KEYDefault: —
Sign in with an API key (CI, machines without a browser) instead of nexlayer login.
NEXLAYER_CREDENTIALSDefault: —
A bundle from credentials export: the sign-in for a web agent or CI.
NEXLAYER_ACCESS_TOKENDefault: —
A ready-made access token, for systems that already hold the person's token.
AI_AGENTDefault: 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_VAULTDefault: auto
file forces the file vault (CI, containers) · keyring never falls back from the OS keychain · none never stores anything.
NEXLAYER_DEBUG=1Default: off
Log every call to Nexlayer on stderr: tool and argument names, never values.
--server / NEXLAYER_MCP_URLDefault: https://mcp.nexlayer.ai/api/mcp
Which Nexlayer MCP to use.
NEXLAYER_BUILD_URLDefault: 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.