Lizard - bootstrap

This is a thin entry point. The authoritative guide lives inside the lizard CLI and is versioned with it, so it always matches the installed CLI version.

Be optimistic: assume the CLI is already available. Try to load the core guide first; only fall back to install / permission help when a command actually fails.

Do NOT improvise lizard commands from this file - the full instructions, flags, and exit codes come from the loaded core guide.

Never run the CLI via npx (npx @lizard-build/cli, npx lizard, etc.). Always use the globally installed lizard binary. npx pulls a throwaway copy into a cache, whose version may not match the loaded guide and which bypasses the install flow below. If lizard is not on PATH, install it (step 2a) - do not reach for npx, even just to check whether it works.

Step 1 - Load the core guide (try first)

Run immediately:

lizard upgrade --check --json
lizard skills get core --json

The guide ships inside the CLI, so an old CLI teaches old commands (sandbox templates and old machines often carry one). If the check says updateAvailable: true, run lizard upgrade --json, then load the guide again. If that answers upgraded: false with a hint, run the hint (for example npm install -g @lizard-build/cli@latest). A check that fails (offline, rate-limited) is no reason to stop: use the guide you have.

lizard skills get core --json returns { name, frontmatter, content, references, ... }. Read content in full - it is the up-to-date Lizard guide to the whole platform: sandboxes, deploys, addons, sign-in, exit codes, billing. Follow it for the rest of the task.

references lists three deeper guides: sandboxes, deploys and sdk (building on Lizard from code). Load one only when the task needs that depth:

lizard skills get core --ref sdk --json

If the CLI rejects --ref (versions before 4.0.45), skip it: on those versions content already holds everything.

If it loads, skip the recovery in Step 2 and go straight to Step 4 to act - assume the user is already logged in. Do not run command -v lizard, do not log in preemptively, and do not install anything beyond the upgrade above. Only drop to Step 3 if a command actually reports no auth.

Step 2 - Recover only on failure

Handle failures from step 1 in order. Stop as soon as one path works and return to the guide.

2a. lizard: command not found (CLI not on PATH)

On macOS or Linux, install it with the install script, then retry step 1:

curl -fsSL https://lizard.build/install.sh | bash

It needs no Node.js and no sudo, and the binary updates itself. It also links lizard into a directory that is already on PATH, so the CLI works in this session right away. If the script's last lines say lizard may not be found, call it as ~/.lizard/bin/lizard for the rest of this session. If they say another lizard comes first on PATH, tell the user: it is usually an old npm install, and npm uninstall -g @lizard-build/cli removes it.

The script ends by signing in. If the machine is not signed in yet, its last lines are a JSON object with status: "pending" and the sign-in links: hand them to the user as described in Step 3.

On Windows, or if the script cannot run (no curl, unsupported system, failed download), install from npm instead:

npm install -g @lizard-build/cli

2b. Install fails with a permission error

Do NOT retry with sudo. On macOS or Linux, use the install script from 2a: it installs into the user's home directory and needs no admin rights.

If npm fails with EACCES, ask the user to run the install themselves in their own terminal (in agents that support in-session shell passthrough, e.g. Claude Code or Cursor, they can type ! npm install -g @lizard-build/cli). If it fails again, suggest a Node version manager (fnm, nvm, mise) so global bins land in a user-writable directory.

After they confirm install, retry lizard skills get core --json.

2c. Core guide unavailable (old CLI, offline, or missing skills command)

Fall back to runtime discovery before running anything:

lizard --help --json
lizard <cmd> --help --json

If the CLI is too old, suggest updating: lizard upgrade.

Step 3 - Sign in (only when needed)

Do NOT sign in proactively. Stay optimistic and assume the user is signed in. You rarely need lizard login, because the sign-in links come to you on their own:

• in the install script's last lines (Step 2a), when it could not sign in yet;
• in the JSON error of any command that fails with exit code 2, under error.body.login.

Both have the same shape: status: "pending", authUrls with one link per sign-in method (github, google), and an instruction. Nothing waits and no browser opens. Ask the user how they sign in to Lizard and give them that link as a clickable URL. Someone who already has an account must use the same method as before: another method opens a second, empty account unless both share a verified email. A new user can pick either.

Once they say the browser shows "CLI authorized", re-run the command that failed, or after an install just carry on: the next lizard command picks the sign-in up. If it still reports pending, they have not finished yet; wait and retry. A link lasts 5 minutes, and the next run prints a new one.

An exit code 2 error without links comes from CI, or from a platform that could not be reached: then retry later, or run lizard login --json, which prints the same object. In CI or on a server nobody can open a link: ask for an API token and set LIZARD_TOKEN, or save it with printf '%s' "$TOKEN" | lizard login --token-stdin. In the user's own terminal, ! lizard login asks GitHub or Google and opens the browser.

Step 4 - Act

If $ARGUMENTS is non-empty, treat it as the user's request and act on it using the guide from step 1 (or the recovery path in step 2). If empty, ask what they want to do on Lizard.