Lizard

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 skills get core --json

This returns { name, frontmatter, content, ... }. Read content in full - it is the complete, up-to-date Lizard usage guide (build pipeline, env precedence, addons, discovery, exit codes, everything). Follow it for the rest of the task.

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. 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)

Install it globally, then retry step 1:

npm install -g @lizard-build/cli

2b. Permission denied (EACCES) on global install

Do NOT retry with sudo. 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):

npm install -g @lizard-build/cli

If they hit EACCES / permission errors again, explain the usual fixes (pick what fits their setup):

• Recommended: use a user-owned npm prefix (no sudo):

  mkdir -p ~/.npm-global
  npm config set prefix ~/.npm-global
  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # or ~/.bashrc
  source ~/.zshrc
  npm install -g @lizard-build/cli
  

• Or use 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 skill 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 - Login (only if not authenticated)

Do NOT log in proactively. Stay optimistic and assume the user is already authenticated. You only land here if a command in Step 4 fails with exit code 2 / "not authenticated". When that happens, run login yourself:

lizard login

This is safe from a tool call: it creates a session, prints an authentication URL to stderr, tries to open the browser, and exits immediately - it does NOT block or poll. Capture that URL and ask the user to log in via that clickable link.

Once they confirm, re-run their original command and continue in Step 4 - the pending session is picked up automatically. If login still reports "pending", they haven't finished yet; wait and retry. (! lizard login in the user's own terminal still works too, but prefer handing over the link.)

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.