# 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`](https://www.npmjs.com/package/@light-cloud/cli) and talks to the same platform as the console and [Light Cloud AI](/deploy-with-ai/mcp-server) - 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 ```bash npm install -g @light-cloud/cli ``` Or run it without installing: ```bash npx @light-cloud/cli login ``` Both `lc` and `light-cloud` are installed as commands. ## Sign in Three ways, for three situations: ```bash 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: ```bash 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](/create/upload). With a connected GitHub repository, `lc create --repo https://github.com/owner/name` sets up an app that [deploys on every push](/platform/deployments). Add `--password ` 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://--.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 ` 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 ```cmds lc login :: Sign in with a browser on this machine. lc login --device --email you@example.com :: Sign in with a short code you approve on any device. Creates the account if the email has none. lc login --api-key :: Sign in with an API key, for CI and other machines. LIGHT_CLOUD_API_KEY in the environment does the same. lc whoami :: Who is signed in and which workspaces they belong to. lc logout :: Sign out and forget the stored credentials. lc orgs :: List the workspaces you belong to. lc org use acme :: Set the default workspace for later commands. No name: pick from a list. lc org current :: Which workspace commands will use here. ``` ### Create and link an app ```cmds lc init :: Link this folder to an app - pick an existing one or create one - and write a .lightcloud file. lc init --app storefront --env production :: Link without asking. lc create --upload :: Create an app from this folder, deploy it and follow the build to the URL. lc create --upload --name storefront --password spring-preview :: Same, named, and gated behind a visitor password from the first deploy. lc create --repo https://github.com/acme/storefront --branch main :: Create an app from a connected GitHub repository; every push to the branch deploys. lc create --repo https://github.com/acme/mono --root apps/web :: Monorepo: build from a folder inside the repository. lc create --upload --framework nextjs --type container --port 3000 :: Override what detection found. See lc frameworks for ids. lc create --upload --no-deploy :: Create without deploying. lc frameworks :: Framework ids the platform understands, for --framework. lc unlink :: Remove the .lightcloud link file from this folder. ``` ### Deploy and inspect ```cmds lc deploy :: Deploy the linked app and follow the build to the live URL. lc deploy storefront --env staging :: Deploy a named app's environment. lc deploy --upload :: Send this folder again (upload apps redeploy from the last archive otherwise). lc deploy --no-watch :: Queue the deployment and return at once. lc apps :: Everything deployed in the workspace. lc apps store :: Filter apps by name. lc status storefront :: One app with its environments, URLs and latest deployment. lc open :: Open the live site in your browser. lc open --console :: Open the app in the Light Cloud console instead. lc rename storefront shop :: Rename an app. lc app update storefront --build "pnpm build" --output dist :: 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 move storefront --folder :: Move an app into a folder (see lc folders); omit --folder for the root. lc app repo-dirs acme/mono --branch main :: Folders in a repository branch, for --root on monorepos. lc delete storefront :: Delete an app and every environment in it. ``` ### Folders and stacks ```cmds lc folders :: Folders (projects) that group apps and databases. lc folder create Clients :: Create a folder; --parent nests it. lc folder delete :: Delete an empty folder. lc stack create opensaas --name billing-demo :: Create and deploy an app from a stack template (needs a connected GitHub account for the repository it creates). ``` ### Logs and deployments ```cmds lc logs -f :: Follow production logs of the linked app. lc logs storefront --env staging --since 2h :: Logs of one environment, how far back to look. lc logs --min-severity WARNING --search "timeout" :: Only warnings and above that contain a string. lc logs -n 500 --no-timestamps :: More history, without timestamps. lc deployments :: The last 10 deployments of the linked app. lc deployments storefront --env staging -n 20 :: History of one environment, up to 20. lc deployment :: One deployment with its build log. lc rollback :: Go back to the previous deployment - no rebuild, the old image is switched in. lc rollback --env staging :: Roll one environment back to a specific deployment. ``` ### Environments ```cmds lc envs storefront :: Environments of an app. lc env get staging --app storefront :: One environment in detail: branch, URL, domain, size, variables count. lc env create staging --branch develop --deploy :: New environment from a branch, deployed right away. lc env create preview --branch feature/x --no-auto-deploy --min 0 --max 1 :: A preview that does not redeploy on push and scales to zero. lc env scale --min 1 :: Keep one instance always on (plan permitting). lc env scale staging --app storefront --max 3 :: Set the instance ceiling. lc env password --set spring-preview :: Visitors must enter this password; takes effect on the next request. lc env password --off :: Make the site public again. lc env update staging --memory 1Gi --auto-deploy off :: Change settings; only the flags given change. Also --name, --build, --output, --port, --cpu, --min, --max. lc env metrics --range 24h :: Requests, latency, errors, instances, cpu and memory. lc env activity :: Who changed what on the environment, newest first. lc env runtime :: What is running now: live deployment, instances, size, region. lc env delete preview --app storefront :: Delete an environment. ``` ### Environment variables ```cmds lc env vars :: Variable names, values masked. lc env vars list --reveal :: Values in clear. lc env vars set DATABASE_URL=postgres://… STRIPE_KEY=sk_… --redeploy :: Set one or more variables and redeploy so they take effect. lc env vars unset OLD_KEY --redeploy :: Remove variables. lc env vars import .env.production :: Merge a .env file over the existing variables. lc env vars import .env.production --replace :: Replace every variable with the file's contents. lc env vars export > .env.backup :: Print the variables in dotenv format. ``` ### Custom domains ```cmds lc domains add shop.example.com :: Attach a domain; prints the DNS records to create. lc domains :: The domain and its DNS and certificate status. lc domains check :: Re-check DNS after creating the records. lc domains retry :: Retry certificate issuance after fixing DNS. lc domains remove :: Detach the domain. ``` ### Databases ```cmds lc dbs :: Databases in the workspace. lc db tiers :: Engines, machine tiers and regions you can create. lc db create shop-db :: A PostgreSQL database on the shared pool, included in every plan. lc db create shop-db --engine mysql :: MySQL instead. lc db create shop-db --tier --region europe-west1 --storage 20 --ha :: A dedicated tier with storage and high availability. lc db get shop-db :: Status, engine, tier, host. lc db url shop-db :: The connection string. Treat it as a secret. lc db url shop-db --details :: Host, port, database, user and password separately. lc env vars set DATABASE_URL="$(lc db url shop-db)" --redeploy :: Put the connection string straight into the app. lc db rotate-password shop-db :: New admin password; apps using the old one must be updated. lc db dump shop-db -o backup.sql.gz :: Download a compressed SQL dump. lc db import backup.sql.gz --db shop-db :: Load a dump into a database; existing data is kept. lc db schema shop-db :: Schemas, tables, columns and row counts. lc db query "select count(*) from orders" --db shop-db :: Run SQL, read-only unless --write. lc db metrics shop-db --range 1h :: Connections, cpu, memory, storage and query load. lc db update shop-db --storage 50 --ha :: Change name, tier, region, storage or high availability. lc db delete shop-db :: Delete the database and all its data. ``` ### Billing ```cmds lc billing :: Plan, card on file and how much of this cycle's usage pool is used. lc billing plans :: Plans this workspace can be on. lc billing plan use pro :: Switch plan. Upgrades confirm and charge the card; downgrades take effect at the next cycle. lc billing card :: The card on file. lc billing card add :: Save a card through a Stripe-hosted page; waits until it is saved. No card number passes through the CLI. lc billing card add --plan pro --no-browser :: Print the link instead of opening it, and switch plan once the card lands. lc billing card remove :: Remove the card on file. lc billing usage :: Usage against the pool this cycle, per resource. lc billing history :: Usage over previous cycles. lc billing invoices :: Invoices, newest first; --status paid|open|failed. lc billing invoice :: One invoice with its lines; --retry charges the card again for a failed one. lc billing outstanding :: Unpaid invoices across the workspaces you own. lc billing limit --set 50 --alert-at 80 :: Monthly spending limit in USD and the alert threshold; --clear removes it; no flags shows it. lc billing details --set company_name="Acme sp. z o.o." vat_number=PL123 country=PL :: Billing address and tax ids on invoices; no flags shows them. ``` ### Workspace and members ```cmds lc org create Clients :: Create a new workspace on the free plan. lc members :: Members of the workspace with their roles. lc member invite sam@example.com --role admin :: Invite by email; the seat is active once they sign in. lc member role user :: Change a member's role. lc member remove :: Remove a member. lc roles :: Roles available in the workspace. ``` ### API keys (paid plans) ```cmds lc keys :: API keys of the workspace. lc key create ci --role user :: Create a key for CI and other machines; the secret is shown once. --expires for an expiry. lc key revoke :: Revoke a key; anything using it stops at once. ``` ### Git providers ```cmds lc git connect gitlab :: One link that signs in and authorises GitLab for this workspace. Also bitbucket, or github for the App install link. lc git repos gitlab :: Repositories reachable through the connected provider. lc git github-status :: GitHub App installations linked to this workspace. ``` ### Account ```cmds lc profile :: Your name and time zone; --first-name, --last-name, --timezone change them. lc devices :: Every signed-in session: browsers, the CLI, MCP servers, VS Code. lc device sign-out :: Sign one session out. lc agent-access :: What this account lets agents do - the switch under Settings > Security > Agents & CLI, read-only here. lc notifications --unread :: Account notifications; --read [id] marks one or all as read. lc support "Build cache seems stale" -m "Details here" :: Send a message to Light Cloud support; --feature files it as a feature request. ``` ### CLI settings ```cmds lc config :: Effective settings and where each comes from. lc config set api-url https://api.staging-light-cloud.com :: Point the CLI at another API. lc config unset api-url :: Back to the default. ``` ## 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 ` 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 ` 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. ```bash LIGHT_CLOUD_API_KEY=lc_… lc deploy --json --yes ``` Coding agents can use `lc` the same way they use `git`: the [MCP server](/deploy-with-ai/mcp-server) is the conversational route, the CLI the scripted one, and both reach every feature. ## Use a different API endpoint ```bash lc config set api-url https://api.staging-light-cloud.com ``` or `--api-url ` / `LIGHT_CLOUD_API_URL` for one command. ## Related - [Light Cloud AI (MCP server)](/deploy-with-ai/mcp-server): The same platform from a conversation in Claude Code, Claude Desktop or Copilot. - [Deploy with AI](/deploy-with-ai/overview): All the AI paths at a glance. - [API keys](/reference/api/authentication): Keys for pipelines and machines.