Light Cloud CLI

lc is the Light Cloud command line: deploy an app and watch the build stream by, tail runtime logs, set environment variables, roll back, manage databases. Everything the console does for an app, from the terminal, with --json for scripts.

$ lc deploy
┌  ☁ Light Cloud deploy
│
│  my-app → production ★
│  Source: github.com/acme/my-app @ main
│
◇  Deployment queued  my-app / production
◇  Cloning repository  2.1s
◇  Building image  58s
◇  Deploying container  14s
◇  Deployed in 1m 16s  https://my-app.acme.light-cloud.io
│
└  Live at https://my-app.acme.light-cloud.io

No account yet? Start here

$ npx @light-cloud/cli login --device --email [email protected]

Type the 8-character code it prints at console.light-cloud.com/device from any device (approve the link in the email we send for a new address). That creates the account on the Free plan — no card, no password, no form — and signs the terminal in. lc billing upgrade lite later, when you want a paid plan: one Stripe Checkout takes the card and the first payment, and the card never passes through lc.

Install

npm install -g @light-cloud/cli
lc --version

Node 18.17 or newer. lc and light-cloud are the same binary.

First run

lc login          # opens the browser; tokens land in ~/.lightcloud/credentials.json
cd my-project
lc init           # link the folder to an existing app, or create one
lc deploy         # deploy and follow the build
lc logs -f        # tail runtime logs

lc login shares its credential file with the Light Cloud MCP server, so signing in once serves both.

Commands

Everything the console can do, as commands. Console-only by design: the account password, two-factor, and the Agents & CLI switch. Copy-ready reference for every command: https://docs.light-cloud.com/deploy-with-ai/cli#command-reference

| Command | What it does | |---|---| | lc login / logout / whoami | Browser sign-in, lc login --device for a code from any device, or lc login --api-key lc_… for machines | | lc orgs, lc org use/current/create | Workspaces; choose the default one; create a new one | | lc init, lc create [--upload] [--password <pw>] | Link this folder to an app; create one from a repository or an upload, optionally behind a visitor password | | lc apps [filter], lc status [app], lc open, lc rename, lc delete | Apps in the workspace and one app in detail | | lc app update/move/repo-dirs | Build settings and defaults; folders; monorepo folders in a repository | | lc deploy [app] [--env x] [--upload] | Deploy and follow; --no-watch to just queue | | lc envs, lc env get/create/update/delete/scale/password | Environments, their settings, the visitor password gate | | lc env vars [set/unset/import/export] | Environment variables; --redeploy to apply | | lc env metrics/activity/runtime | Metrics, who changed what, what is running now | | lc logs [-f] [--since 2h] [--min-severity WARNING] [--search text] | Runtime logs | | lc deployments, lc deployment <id>, lc rollback [id] | History, the build log of one deployment, roll back without a rebuild | | lc domains, lc domains add/check/retry/remove | Custom domains. www and the root are set up together. Shows a live DNS check, which records are required or optional, which to delete, and says when a domain has a certificate but does not point here. add --force replaces a working domain before the new one's DNS is ready. Custom domains come with the paid plans: on Free add is refused with PLAN_ENTITLEMENT, and the hint names the plan to upgrade to. A domain already on a Free workspace goes on hold 14 days after the owner is emailed, until the workspace is on a paid plan | | lc folders, lc folder create/delete | Folders that group apps and databases | | lc stack create <id> | An app from a stack template (e.g. Open SaaS) | | lc dbs, lc db create/get/update/url/rotate-password/dump/import/schema/query/metrics/delete | Databases: lifecycle, connection string, backups, schema, SQL, metrics | | lc billing, lc billing plans, lc billing upgrade <plan> [--annual], lc billing card add/remove | Plan, included usage, a one-step upgrade and the payment card (both through Stripe-hosted pages). lc billing plan use is the same as upgrade | | lc billing usage/history/invoices/invoice/outstanding/alerts/details | Usage, invoices, usage alerts, billing address and tax ids | | lc members, lc member invite/remove/role, lc roles | Workspace members | | lc keys, lc key create/revoke | API keys for CI (paid plans; the secret is shown once) | | lc git connect/repos/github-status | One link to connect GitLab or Bitbucket; the GitHub App install link | | lc profile, lc devices, lc device sign-out, lc agent-access | Your name and time zone; signed-in sessions; what agents may do | | lc notifications, lc support | Notifications; a message to support | | lc config, lc unlink | Endpoint settings; remove the link file |

Every command takes --json, --org <workspace>, --yes and --api-url.

Settings → Security → Agents & CLI in the console can switch the CLI off, or keep groups of actions (deploy, delete, settings, databases, billing, workspace, API keys) console-only. A refused command says so and names the setting; the session lc login receives is marked as the CLI's, so the switch holds regardless of flags.

Plans and billing

Every workspace starts on Free: $1 of usage a month, unlimited static sites, 3 server apps, no card. When Free's $1 is used up, server apps and deploys pause until the next cycle and static sites keep serving; a free workspace is never billed. Paid plans include usage worth their price, and extra usage goes on the next invoice (unless you chose a usage limit at checkout). Annual billing is two months free.

• lc billing — the plan, the card on file, and usage this cycle against what the plan includes; says when the workspace is paused and which plan brings it back.
• lc billing plans — every plan with its monthly and annual price, the usage it includes, and its limits.
• lc billing upgrade <plan> [--annual] — moves to a plan in one step. With a card on file it is charged at once; without one, a Stripe Checkout page (opened here, or a link for any device with --no-browser) takes the card and the first payment together, and the plan switches as soon as Stripe confirms. Downgrades wait for the end of the paid period.
• lc billing usage — usage this cycle per app and database, removed ones included.
• lc billing alerts [--at <usd> | --clear] — the 80% and 100% emails always send; add one extra alert at a dollar amount. Shows the usage limit on paid plans.

A command refused by a plan limit names the plan that includes it, with the command to run: Lite includes it ($5 a month): run lc billing upgrade lite.

How a folder is linked

lc init writes a .lightcloud file:

{
  "organisationId": "…",
  "applicationId": "…",
  "environmentId": "…",
  "applicationName": "my-app",
  "framework": "nextjs",
  "deploymentType": "container"
}

Commands run from that folder (or any subfolder) act on that app. The same file is read by the MCP server and the VS Code extension. Commit it if the whole team deploys the same app; ignore it if not.

CI and scripts

Create an API key in the console (Organisation settings → API keys; paid plans), then:

export LIGHT_CLOUD_API_KEY=lc_…
lc deploy --yes            # in a folder with .lightcloud
lc apps --json | jq '.[].name'

An API key is bound to one workspace, so --org is not needed. Without a terminal, prompts are never shown: anything that would have asked fails with the flag to pass instead.

Exit codes: 0 ok · 1 error · 2 usage · 3 not signed in · 4 not found · 5 the deployment or provisioning failed · 130 cancelled.

API endpoint

The CLI talks to https://api.light-cloud.com and https://console.light-cloud.com by default; nothing needs setting. To point it somewhere else, use lc config set api-url <url> or LIGHT_CLOUD_API_URL (per command: LIGHT_CLOUD_API_URL=http://localhost:5001 lc apps). The console URL is inferred from the API URL (api. → console.); override it with lc config set console-url … or LIGHT_CLOUD_CONSOLE_URL.

Development

npm install
npm run dev -- apps            # run from source
npm run typecheck
npm test
npm run build                  # dist/index.js, single file
node dist/index.js --help

Framework detection rules live in src/lib/detection/catalogue.ts, a snapshot of the backend catalogue; the header of that file says how to regenerate it.