Skip to content
DocscloudDocumentation

CLI

Deploy to Lunora Cloud, roll a release back, and eject your data and config to your own Cloudflare account — all from the one `lunora` binary, authenticated with an org deploy key.

Last updated:

The same lunora binary that runs your dev server ships to the managed cloud. lunora cloud is the command group for it: deploy a build, roll back to a retained release, and eject everything to your own Cloudflare account.

LUNORA_DEPLOY_KEY=… lunora cloud deploy --project prj_123 --bundle dist/index.js

Authentication

Every subcommand authenticates with an org deploy key, read from the LUNORA_DEPLOY_KEY environment variable.

It is deliberately not a flag and not a config file. A flag lands in your shell history and in CI logs; a file gets committed. An environment variable is the one place a secret can live that neither happens by accident.

VariablePurpose
LUNORA_DEPLOY_KEYThe org deploy key. Required. Issue one from the dashboard's Deploy keys tab.
LUNORA_CLOUD_URLControl-plane API URL. Required unless you pass --url.

Deploy keys carry a capability. A deploy key is the full key your CI uses; an ingest key is telemetry-only and is rejected by these commands, so a leaked ingest token cannot ship code. See Monitoring.

lunora cloud deploy

Uploads a prebuilt worker bundle and streams the deployment's progress until it goes live or fails.

lunora build
LUNORA_DEPLOY_KEY=… lunora cloud deploy --project prj_123 --bundle dist/index.js
FlagMeaning
--projectTarget project id. Required.
--bundlePath to the prebuilt worker bundle to upload. Required.
--nameWorker/script name. Defaults to name in your wrangler config.
--kindproduction (default), preview, or dev.
--branchGit branch to record against the deployment — what preview URLs are keyed on.
--urlControl-plane API URL, if not using LUNORA_CLOUD_URL.
--outWrite the request body to this file instead of uploading it (see below).

It reads your wrangler config — the built one a Vite build points .wrangler/deploy/config.json at when it exists (that is where the Cloudflare Vite plugin records your client build as assets), otherwise wrangler.jsonc — and sends the full binding manifest — the same document lunora info --bindings prints: every binding your Worker reads off env (KV, D1, R2, Durable Objects, queues, Workflows, AI, and the rest), plus compatibility_date and compatibility_flags. The platform provisions or binds what it supports and refuses the rest by name before anything is created, so an unsupported binding fails the deploy instead of surfacing as an undefined env.X later. A wrangler section the manifest does not model is reported as a warning; the deploy goes ahead without it.

triggers.crons travel with it. Workers-for-Platforms drops cron triggers on namespaced workers, so the control plane fans those ticks out to your deployment itself — you do not configure that.

When your wrangler config has an assets section, the files under assets.directory (resolved relative to the wrangler file) are uploaded too, along with its html_handling, not_found_handling, and run_worker_first settings. Build first: a missing or empty directory is an error. A .assetsignore in that directory excludes matching files (one glob per line; a leading / anchors to the directory, and ! re-includes are not supported). A single file over 25 MiB, or more than 50 MiB in total, is refused.

Custom headers and redirects work as they do on Cloudflare: put a _headers or _redirects file at the root of assets.directory — for example Cache-Control: public, max-age=31536000, immutable for /assets/*. Neither is served as a file; their contents travel with the deploy (the command says so) and every Lunora Cloud target applies them to static-asset responses, not to responses your Worker returns. Cloudflare's limits are checked before anything is sent: 100 header rules and 2,000 characters a line in _headers; 2,000 static and 100 dynamic rules and 1,000 characters a line in _redirects (a rule with a splat or :placeholder source, and every rule after the first such one, counts as dynamic).

The command exits non-zero unless the deployment reaches live.

--out <file> stops short of the upload: it writes the exact request body — bundle, manifest, crons and assets, plus --project, --name/wrangler name, --kind and --branch when known — to the file and exits. Nothing is sent and nothing authenticates, so it needs neither LUNORA_DEPLOY_KEY nor a URL, and --project becomes optional. The file never contains the deploy key. Lunora Cloud's own build box uses it to turn a git push into a release with your project's pinned CLI.

Every deploy updates the project's one Worker in place and goes out to all traffic at once — Workers for Platforms cannot stage a user Worker's version, so there are no canary or percentage rollouts. The health check therefore runs after the new code is already serving: if it fails, the deployment is marked failed and the previous live release is put back automatically.

lunora cloud rollback

Puts a retained earlier release back on the project's Worker. A project has one Worker, updated in place so its Durable Object data survives every release; each deploy's bundle is stored, and a rollback re-provisions that stored bundle — no rebuild. The last three superseded releases are retained. A rollback that would drop a Durable Object class the live release binds is refused, because dropping a class deletes its data.

lunora cloud rollback dep_456 --org org_789 --yes
FlagMeaning
--orgOrganization id that owns the deployment. Required.
--yesConfirm. Required — a rollback shifts live traffic.

--yes is not ceremony. Without it the command refuses and tells you what would have happened, because the effect is immediate and user-visible.

lunora cloud eject

Packages a deployment for your own Cloudflare account: your full data snapshot, your project's config ready for another account — as a wrangler.jsonc and as an Alchemy 2 program, the tool Lunora Cloud itself provisions with — and a README with the restore steps.

Run it from the project directory. The config is derived from your own wrangler.jsonc, so every binding the app uses (D1, KV, R2, queues and their consumers, Durable Objects, assets, AI, workflows, vars, crons, …) carries over; with no wrangler config there, eject stops before contacting the control plane.

lunora cloud eject dep_456          # writes ./eject
lunora cloud eject dep_456 --out backup
FlagMeaning
--outOutput directory. Defaults to ./eject.

Four files land in it:

FileWhat it is
export.ndjsonYour full data snapshot — every shard plus the global tables.
wrangler.jsoncYour config, named after the deployment's script, with the old account's D1/KV/Hyperdrive ids replaced by <create with: …> placeholders.
alchemy.run.tsThe same config as an Alchemy 2 stack. Alchemy creates the resources itself, so there are no ids to paste; run it with alchemy deploy --stage ….
README.mdThe restore steps for both paths, with your project's names filled in.

The Alchemy program keeps its state in .alchemy/ next to your project (localState()); swap in Cloudflare.state() to keep it in your account. It adopts resources that already exist by name instead of re-creating them. Sections it cannot express — service bindings, Hyperdrive (whose origin credentials are not in wrangler.jsonc), and the like — are printed as a warning and listed in the README.

Ejecting changes nothing. It is a read: your managed deployment keeps serving afterwards, and you can run it whenever you like — including just to confirm that you can. That is the point. A portability guarantee you have never exercised is a claim, not a feature.

The control plane holds your tenant's admin token, uses it, and keeps it — the CLI only ever receives the resulting bytes. So ejecting never leaves a long-lived tenant credential on your disk or in your shell history.

The snapshot streams straight to disk, so its size is not bounded by memory on either side. It is written first and checked against the export's end marker as it arrives: an export that fails or is cut short leaves nothing behind rather than a half-written directory that looks like a backup.

Reading logs

lunora cloud ships code; lunora logs reads it back. That command has three independent sources:

SourceReadsNeeds
(default)A deployed Worker, live (wrangler tail)A deployment
--durableThe persisted ctx.log archive in R2A Pipeline → R2 Data Catalog table
--localWhat your running dev server capturedNothing — just lunora dev running
lunora logs --local                              # the last 200 captured lines
lunora logs --local --search "checkout"          # substring match
lunora logs --local --trace-id 37cfd081…         # one request's whole output
lunora logs --local --level error --limit 20     # errors only
lunora logs --local --url http://localhost:5174  # when Vite picked another port

--local reads the dev runtime's own capture, so it needs no deploy and no credentials. It finds the server through .lunora/dev.json, so a backend-only lunora dev on wrangler's port (8787) is read without --url; with no running lunora dev it falls back to http://localhost:5173. Lines are formatted by the same formatter lunora dev uses, so a ctx.log call reads identically in both places.

Two honest limits. The capture starts when the dev server does and holds only what it has seen since — restart the server and it is empty again. And --level there filters the console channel (info, warn, error), not the seven-tier ctx.log ramp, because the channel is what the capture records; the finer level still shows in the formatted line.

Push-to-deploy, without the CLI

Once a project is connected to a repository through the Lunora Cloud GitHub App, a push to the default branch is built on the platform and released as production, and a pull request from the same repository gets a preview, with build logs and a commit status. The build box runs your project's own pinned @lunora/cli and calls lunora cloud deploy --out to produce the release, so a project needs a CLI release that includes --out before git deploys work for it; an older CLI fails the build with a message saying so. Pull requests from forks are built but never deployed, because a deploy carries the project's secrets.

What is not here yet

Lunora Cloud is early: the commands above talk to a control plane that is in private early access; see the roadmap.

Deploying into your own Cloudflare account or onto your own server needs no command of its own: the deploy target is a setting of the project, chosen in the studio, and lunora cloud deploy sends the same release whichever target it lands on. Both targets are in private early access too, and each page says what does not work there yet.