Install @light-cloud/cli and run lc login, lc deploy, lc logs, lc billing from a terminal or a script. Sign in with a code from any device, deploy a folder or a repository, manage plans and the payment card, all with --json output for agents and CI.

Light Cloud CLI

lc is Light Cloud from the terminal: sign in, create apps, deploy, tail logs, manage environments, databases, domains and billing. It is published on npm as @light-cloud/cli and talks to the same platform as the console and Light Cloud AI - an app created with lc shows up on the dashboard like any other.

Every command takes --json, so the CLI is as usable by an agent or a CI job as by a person.

Requirements#

Node.js 18 or later.
A Light Cloud account - or not: lc login --device creates one for an email that has none.

Install#

npm install -g @light-cloud/cli

Or run it without installing:

npx @light-cloud/cli login

Both lc and light-cloud are installed as commands.

Three ways, for three situations:

lc login                       # opens your browser (Google, GitHub, or email)
lc login --device              # a code to type on any device, no browser needed here
lc login --api-key lc_…        # CI and machines, with a key from Organisation settings > API keys

With a code (`--device`)#

On a machine without a browser - an SSH box, a container, a Codespace - lc login --device asks for your email and prints an 8-character code:

│  Open https://console.light-cloud.com/device on any device, sign in, and enter the code:
│
│      WXYZ-2345
│
│  The code expires in 15 minutes.
◐ Waiting for the code to be approved…

Open the link on anything with a browser (a phone works), sign in, type the code, approve. The terminal finishes on its own. If the email has no account yet, the email we send carries a link that creates one when you approve - no password, no form. On Linux with no DISPLAY, lc login picks this flow automatically.

Devices signed in this way are listed under Settings > Security > Connected devices in the console, where they can be signed out.

Credentials are stored in ~/.lightcloud/credentials.json. lc whoami shows the account and its workspaces; lc logout forgets the session.

Deploy your first app#

From a project folder:

lc init          # link this folder to an app (existing or new)
lc deploy        # deploy and follow the build
lc logs -f       # tail runtime logs

lc init detects the framework, asks the few questions it cannot answer from the folder, and writes a .lightcloud file so later commands need no arguments. No Git remote is required - a plain folder deploys as an upload. With a connected GitHub repository, lc create --repo https://github.com/owner/name sets up an app that deploys on every push. Add --password <pw> to either form and the site asks visitors for it from the first deploy.

Detection is the console's, not the CLI's. The folder is read locally first so lc init can show what it found, but once the archive is uploaded the backend inspects it with the same detector the console uses for a connected repository, and the app is created from that reading - so an upload and a repository deploy the same code the same way. An explicit flag (--framework, --type, --build, --output, --port) still wins over both. When the backend's reading differs from the local one, lc says so:

ℹ Light Cloud read the source as nextjs (container).

When the build finishes, lc deploy prints Live at https://<env>-<app>-<workspace>.light-cloud.io; with --json the same URL is in the url field.

Command reference#

Every command below has a copy button. [app] defaults to the app linked in this folder, --env to production, and the workspace to your default one (--org <name> overrides it for one command). Add --json to any command for machine-readable output, -y to skip confirmations, and --help for the full flag list.

Account and workspaces#

lc login

lc login --device --email you@example.com

lc login --api-key <key>

Who is signed in and which workspaces they belong to.

lc whoami

Sign out and forget the stored credentials.

lc logout

List the workspaces you belong to.

lc orgs

Set the default workspace for later commands. No name: pick from a list.

lc org use acme

Which workspace commands will use here.

lc org current

Create and link an app#

Link this folder to an app - pick an existing one or create one - and write a .lightcloud file.

lc init

Link without asking.

lc init --app storefront --env production

Create an app from this folder, deploy it and follow the build to the URL.

lc create --upload

Same, named, and gated behind a visitor password from the first deploy.

lc create --upload --name storefront --password spring-preview

Create an app from a connected GitHub repository; every push to the branch deploys.

lc create --repo https://github.com/acme/storefront --branch main

Monorepo: build from a folder inside the repository.

lc create --repo https://github.com/acme/mono --root apps/web

Override what detection found. See lc frameworks for ids.

lc create --upload --framework nextjs --type container --port 3000

Create without deploying.

lc create --upload --no-deploy

Framework ids the platform understands, for --framework.

lc frameworks

Remove the .lightcloud link file from this folder.

lc unlink

Deploy and inspect#

Deploy the linked app and follow the build to the live URL.

lc deploy

Deploy a named app's environment.

lc deploy storefront --env staging

Send this folder again (upload apps redeploy from the last archive otherwise).

lc deploy --upload

Queue the deployment and return at once.

lc deploy --no-watch

Everything deployed in the workspace.

lc apps

Filter apps by name.

lc apps store

One app with its environments, URLs and latest deployment.

lc status storefront

Open the live site in your browser.

lc open

Open the app in the Light Cloud console instead.

lc open --console

Rename an app.

lc rename storefront shop

Change build settings; only the flags given change. Also --root, --framework, --runtime, --port, --memory, --cpu, --min, --max, --auto-deploy-branches, --github-checks, --github-pr-comments.

lc app update storefront --build "pnpm build" --output dist

Move an app into a folder (see lc folders); omit --folder for the root.

lc app move storefront --folder <id>

Folders in a repository branch, for --root on monorepos.

lc app repo-dirs acme/mono --branch main

Delete an app and every environment in it.

lc delete storefront

Folders and stacks#

Folders (projects) that group apps and databases.

lc folders

Create a folder; --parent <id> nests it.

lc folder create Clients

Delete an empty folder.

lc folder delete <id>

Create and deploy an app from a stack template (needs a connected GitHub account for the repository it creates).

lc stack create opensaas --name billing-demo

Logs and deployments#

Follow production logs of the linked app.

lc logs -f

Logs of one environment, how far back to look.

lc logs storefront --env staging --since 2h

Only warnings and above that contain a string.

lc logs --min-severity WARNING --search "timeout"

More history, without timestamps.

lc logs -n 500 --no-timestamps

The last 10 deployments of the linked app.

lc deployments

History of one environment, up to 20.

lc deployments storefront --env staging -n 20

One deployment with its build log.

lc deployment <id>

Go back to the previous deployment - no rebuild, the old image is switched in.

lc rollback

Roll one environment back to a specific deployment.

lc rollback <id> --env staging

Environments#

Environments of an app.

lc envs storefront

One environment in detail: branch, URL, domain, size, variables count.

lc env get staging --app storefront

New environment from a branch, deployed right away.

lc env create staging --branch develop --deploy

A preview that does not redeploy on push and scales to zero.

lc env create preview --branch feature/x --no-auto-deploy --min 0 --max 1

Keep one instance always on (plan permitting).

lc env scale --min 1

Set the instance ceiling.

lc env scale staging --app storefront --max 3

Visitors must enter this password; takes effect on the next request.

lc env password --set spring-preview

Make the site public again.

lc env password --off

Change settings; only the flags given change. Also --name, --build, --output, --port, --cpu, --min, --max.

lc env update staging --memory 1Gi --auto-deploy off

Requests, latency, errors, instances, cpu and memory.

lc env metrics --range 24h

Who changed what on the environment, newest first.

lc env activity

What is running now: live deployment, instances, size, region.

lc env runtime

Delete an environment.

lc env delete preview --app storefront

Environment variables#

Variable names, values masked.

lc env vars

Values in clear.

lc env vars list --reveal

Set one or more variables and redeploy so they take effect.

lc env vars set DATABASE_URL=postgres://… STRIPE_KEY=sk_… --redeploy

Remove variables.

lc env vars unset OLD_KEY --redeploy

Merge a .env file over the existing variables.

lc env vars import .env.production

Replace every variable with the file's contents.

lc env vars import .env.production --replace

Print the variables in dotenv format.

lc env vars export > .env.backup

Custom domains#

Attach a domain; prints the DNS records to create.

lc domains add shop.example.com

The domain and its DNS and certificate status.

lc domains

Re-check DNS after creating the records.

lc domains check

Retry certificate issuance after fixing DNS.

lc domains retry

Detach the domain.

lc domains remove

Databases#

Databases in the workspace.

lc dbs

Engines, machine tiers and regions you can create.

lc db tiers

A PostgreSQL database on the shared pool, included in every plan.

lc db create shop-db

MySQL instead.

lc db create shop-db --engine mysql

A dedicated tier with storage and high availability.

lc db create shop-db --tier <id> --region europe-west1 --storage 20 --ha

Status, engine, tier, host.

lc db get shop-db

The connection string. Treat it as a secret.

lc db url shop-db

Host, port, database, user and password separately.

lc db url shop-db --details

Put the connection string straight into the app.

lc env vars set DATABASE_URL="$(lc db url shop-db)" --redeploy

New admin password; apps using the old one must be updated.

lc db rotate-password shop-db

Download a compressed SQL dump.

lc db dump shop-db -o backup.sql.gz

Load a dump into a database; existing data is kept.

lc db import backup.sql.gz --db shop-db

Schemas, tables, columns and row counts.

lc db schema shop-db

Run SQL, read-only unless --write.

lc db query "select count(*) from orders" --db shop-db

Connections, cpu, memory, storage and query load.

lc db metrics shop-db --range 1h

Change name, tier, region, storage or high availability.

lc db update shop-db --storage 50 --ha

Delete the database and all its data.

lc db delete shop-db

Billing#

Plan, card on file and how much of this cycle's usage pool is used.

lc billing

Plans this workspace can be on.

lc billing plans

Switch plan. Upgrades confirm and charge the card; downgrades take effect at the next cycle.

lc billing plan use pro

The card on file.

lc billing card

Save a card through a Stripe-hosted page; waits until it is saved. No card number passes through the CLI.

lc billing card add

Print the link instead of opening it, and switch plan once the card lands.

lc billing card add --plan pro --no-browser

Remove the card on file.

lc billing card remove

Usage against the pool this cycle, per resource.

lc billing usage

Usage over previous cycles.

lc billing history

Invoices, newest first; --status paid|open|failed.

lc billing invoices

One invoice with its lines; --retry charges the card again for a failed one.

lc billing invoice <id>

Unpaid invoices across the workspaces you own.

lc billing outstanding

Monthly spending limit in USD and the alert threshold; --clear removes it; no flags shows it.

lc billing limit --set 50 --alert-at 80

Billing address and tax ids on invoices; no flags shows them.

lc billing details --set company_name="Acme sp. z o.o." vat_number=PL123 country=PL

Workspace and members#

Create a new workspace on the free plan.

lc org create Clients

Members of the workspace with their roles.

lc members

Invite by email; the seat is active once they sign in.

lc member invite sam@example.com --role admin

Change a member's role.

lc member role <userId> user

Remove a member.

lc member remove <userId>

Roles available in the workspace.

lc roles

API keys (paid plans)#

API keys of the workspace.

lc keys

Create a key for CI and other machines; the secret is shown once. --expires <date> for an expiry.

lc key create ci --role user

Revoke a key; anything using it stops at once.

lc key revoke <id>

Git providers#

One link that signs in and authorises GitLab for this workspace. Also bitbucket, or github for the App install link.

lc git connect gitlab

Repositories reachable through the connected provider.

lc git repos gitlab

GitHub App installations linked to this workspace.

lc git github-status

Account#

Your name and time zone; --first-name, --last-name, --timezone change them.

lc profile

Every signed-in session: browsers, the CLI, MCP servers, VS Code.

lc devices

Sign one session out.

lc device sign-out <sessionId>

What this account lets agents do - the switch under Settings > Security > Agents & CLI, read-only here.

lc agent-access

Account notifications; --read [id] marks one or all as read.

lc notifications --unread

Send a message to Light Cloud support; --feature files it as a feature request.

lc support "Build cache seems stale" -m "Details here"

CLI settings#

Effective settings and where each comes from.

lc config

Point the CLI at another API.

lc config set api-url https://api.staging-light-cloud.com

Back to the default.

lc config unset api-url

What stays in the console#

Changing the account password, two-factor settings, and the Agents & CLI switch are console-only. Everything else the console can do has a command above.

Turning the CLI off#

Settings → Security → Agents & CLI in the console decides what the CLI, the MCP server and the VS Code extension may do on your account: a master switch, then groups you can keep console-only (deploying, deleting, settings, databases, plan and payment, workspace and members, API keys). Reading is always allowed. A refused command says so and points there:

✖ Agents may not delete apps, environments and databases on this account.
  Allow it under Settings → Security → Agents & CLI in the console, or do this step there.

The switch is enforced from the session itself - lc login receives a session marked as the CLI's - so it holds regardless of flags or headers. lc agent-access shows the current setting. API keys are separate: bound to a workspace, revoked with lc key revoke.

Billing from the terminal#

lc billing shows the plan, the card on file and how much of this cycle's usage pool is used. lc billing plans lists what the workspace could be on; lc billing plan use <id> switches (upgrades confirm and charge the card, downgrades take effect at the next cycle).

A card is added through Stripe's hosted page - lc billing card add prints a link, opens it if there is a browser, and waits until the card is saved. The link works on any device, and no card number ever passes through the CLI. Add --plan pro to switch plan as soon as the card is on file.

When something needs a plan change or a card, the refusal says which command unblocks it:

✖ A payment method is required for paid plans.
  Run lc billing card add, then this command again.

For agents and CI#

--json on any command prints one JSON document on stdout and nothing else; errors go to stderr with a non-zero exit code (2 usage, 3 auth, 4 not found).
--yes answers confirmations; --org <name> pins the workspace.
LIGHT_CLOUD_API_KEY in the environment signs in without a stored session - the usual setup for a pipeline running from a folder with a .lightcloud file.

LIGHT_CLOUD_API_KEY=lc_… lc deploy --json --yes

Coding agents can use lc the same way they use git: the MCP server is the conversational route, the CLI the scripted one, and both reach every feature.

Use a different API endpoint#

lc config set api-url https://api.staging-light-cloud.com

or --api-url <url> / LIGHT_CLOUD_API_URL for one command.

Light Cloud AI (MCP server)The same platform from a conversation in Claude Code, Claude Desktop or Copilot.Deploy with AIAll the AI paths at a glance.API keysKeys for pipelines and machines.