# Use Lampwick from the command line

> The Lampwick CLI (`lampwick`) runs every API operation as a command, logs in through your browser, records deploys from CI and follows logs live.

`lampwick` is the command line for Lampwick: every operation of the [API](/docs/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](/docs/api/) (every command is one API call) or the [deploy recipes](/docs/deploys/).

## Install

```bash
brew install lmpwck/tap/lampwick
```

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

```bash
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

```bash
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:

```bash
lampwick auth status
```

```text
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

```bash
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

```bash
lampwick status
```

```text
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
```

```bash
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:

```bash
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:

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

```text
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](/docs/deploys/). 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](/docs/deploys/) on every release.