Use Lampwick from the command line

lampwick is the command line for Lampwick: every operation of the API is a command, plus a browser login, deploy markers from CI and live logs. It runs on macOS and Linux, on arm64 and x64.

The lampwick CLI isn't published yet, so the install commands below don't work yet. Until then, use the API (every command is one API call) or the deploy recipes.

Install

Terminal

brew install lmpwck/tap/lampwick

Or with npm, or the install script, which checks the download's SHA-256:

Terminal

npx lampwick --version
curl -fsSL https://lampwick.dev/install.sh | sh

The script installs to /usr/local/bin when it can write there, else to ~/.local/bin.

Log in

Terminal

lampwick login

Your browser opens Lampwick's consent page. Choose Read & write to change things from the command line, or Read-only (recommended) to only look, then click Connect. The login lasts 60 days from its last use and refreshes itself. It shows up under Connected apps on Account & security as Lampwick CLI on YOUR-COMPUTER.

The login is stored in the macOS keychain, or in ~/.config/lampwick/credentials.json (readable only by you) on Linux. Check it with:

Terminal

lampwick auth status

server        https://app.lampwick.dev
account       ada@example.com
login         browser login, read & write
token from    the macOS keychain

A browser login can do what a connected app can, and no more: it can't manage API tokens or connected apps, invite or change team members, change billing, alert channels or status pages, delete a team, rotate an ingest token or change a browser key. Use the dashboard, or log in with an API token: lampwick login --with-token < token.txt. lampwick logout removes the login and disconnects it.

Link a folder to a project

Terminal

cd ~/code/webshop
lampwick use acme/webshop

This writes .lampwick in the root of the git repository. It holds no secrets, so you can commit it. When it names a server other than app.lampwick.dev or the one you last logged in to, the CLI doesn't send LAMPWICK_TOKEN or a token from .env there until you name that server with --server or LAMPWICK_URL (a changed .lampwick in a repository can't collect your tokens). Commands in that folder then use the project when you leave it out. lampwick init does the same and also offers to write the project's ingest token to .env as LAMPWICK_TOKEN; it asks first, and --yes skips the question.

Projects are team/project, a project's URL name when only one project has it, or an id. Issues are their number: 42. Monitors and deploys take their id, or '#3' for the number in the dashboard URL (in quotes, or bash reads # as the start of a comment).

Examples

Terminal

lampwick status

northwind/storefront  https://app.lampwick.dev/northwind/storefront

Issues    12 open issues
  REF  STATUS  CLASS                           MESSAGE                        OCCURRENCES  LAST SEEN
  #1   open    …oquent\ModelNotFoundException  No query results for model […  181          1h ago
  #2   open    …ception\NotFoundHttpException  The route old-shop/index.php…  304          1h ago
  #4   open    …alidation\ValidationException  The quantity field must be a…  47           11h ago
  #9   open    Swift_TransportException        Expected response code 250 b…  4            20h ago
  #7   open    RedisException                  read error on connection to …  5            22h ago
  and 7 more: lampwick issues

Monitors  all 3 up

Deploy    v2026.11.10 22h ago by github-actions

Terminal

lampwick issues                       # open issues of the linked project
lampwick issues resolve 2             # also: ignore, reopen
lampwick issues acme/blog --status all --limit 20
lampwick logs --follow --level warning  # live; times in your local time zone
lampwick monitors create https://example.com --name Homepage --interval-secs 300
lampwick teams members invite acme bob@example.com --role member
lampwick open                         # the project's dashboard page

lampwick --help lists every command, and lampwick COMMAND --help shows its arguments and the API operation behind it. Tables fit the width of your terminal; lampwick issues get 42 (or issues view 42: every get is also view) shows one issue in full, with durations in ms. Each API field is a flag (interval_secs is --interval-secs). For a body the flags can't express, pass JSON: --data '{…}', --data @body.json, or --data - for stdin. lampwick api /projects/3/issues -q status=all calls any API path.

Shell completion

lampwick completion SHELL prints a completion script for bash, zsh, fish, elvish or powershell. For zsh:

Terminal

lampwick completion zsh > "${fpath[1]}/_lampwick"

Then start a new shell. For bash, write it to ~/.local/share/bash-completion/completions/lampwick; for fish, to ~/.config/fish/completions/lampwick.fish.

Output in scripts

In a terminal you get tables with color; NO_COLOR turns color off. When the output is piped, it is tab-separated without a header, ids first:

Terminal

lampwick issues list --status all | cut -f2,3

1	open
2	resolved

--json prints the API's JSON response as it is. Tables and tab-separated output never show tokens or secrets; --json does, because that is the API's answer.

Exit code	Meaning
`0`	Done
`1`	The API refused (its code and message are printed, for example `project not found (404 not_found)`), or the server couldn't be reached
`2`	Usage: an unknown command, a missing or invalid argument, a name that matches more than one project
`4`	Not logged in, or the token was refused

A command that deletes something asks first in a terminal. In a script it needs --yes.

Record deploys from CI

lampwick deploy records a deploy marker. In CI it uses the project's ingest token from LAMPWICK_TOKEN, the same secret the deploy recipes use, and fills in the version, commit, author and repository from GitHub Actions, GitLab CI, Bitbucket Pipelines, Laravel Forge or Vercel variables, or from git.

YAML

- name: Record deploy in Lampwick
  env:
    LAMPWICK_TOKEN: ${{ secrets.LAMPWICK_TOKEN }}
  run: npx --yes lampwick deploy --no-fail

The version is --version, LAMPWICK_DEPLOY, the tag of the commit, or the first 12 characters of the commit. The environment is --environment, VERCEL_ENV, CI_ENVIRONMENT_NAME or production. --dry-run prints what it would send. A network error or a 5xx is retried twice. --no-fail turns a failure into a warning, so a missing marker doesn't fail your deploy.

On a Forge or Ploi server, lampwick deploy reads LAMPWICK_TOKEN from the site's .env. Logged in with your account instead, it records the deploy on the linked project.

Environment variables

Variable	What it does
`LAMPWICK_TOKEN`	An API token (`lwp_…`) to use instead of the login, or a project's ingest token for `lampwick deploy`
`LAMPWICK_URL`	The server, default `https://app.lampwick.dev`. It must be `https://`; plain `http://` only works for localhost.
`LAMPWICK_PROJECT`	The project to use when you leave it out, instead of `.lampwick`
`LAMPWICK_CONFIG_DIR`	Where the login and settings are kept, default `~/.config/lampwick`
`NO_COLOR`	No color in tables

Troubleshooting

Message	Cause	Fix
`not logged in to https://app.lampwick.dev: run lampwick login, or set LAMPWICK_TOKEN to an API token`	No login for this server.	Run `lampwick login`, or set `LAMPWICK_TOKEN` in CI.
`this API token is read-only: it can't change anything (403 read_only_token)`	You chose Read-only when you logged in, or the token is read-only.	Run `lampwick login` again and choose Read & write.
`"blog" is more than one project: acme/blog, side/blog; use team/project`	Two teams have a project with that URL name.	Use `team/project`.
`which project? Give it (team/project), or link this folder`	No project given and the folder isn't linked.	Run `lampwick use team/project`.
`your login expired or was revoked`	60 days unused, a password reset, a change of two-factor settings, or Disconnect on the account page.	Run `lampwick login`.

Next: record deploys on every release.