# Coding agents

Lizard is designed to be driven by AI coding agents as easily as by humans. The CLI ships an **embedded skill** that teaches an agent the whole platform, and every command is **self-describing** via `--json` so agents never have to guess.

## The embedded skill

The authoritative usage guide lives inside the CLI and is versioned with it, so it always matches the installed version. An agent reads it with:

```bash
lizard skills get core --json
```

This returns `{ name, frontmatter, content, … }` — `content` is the complete guide (build pipeline, env precedence, addons, discovery, exit codes). Related subcommands:

```bash
lizard skills list        # available embedded skills
lizard skills get core    # the core guide
lizard skills path        # where skills are stored
```

Because the guide is bundled with the binary, `lizard upgrade` updates the agent's instructions too.

## Self-describing commands

Agents discover exact flag shapes at runtime instead of relying on memorized syntax:

```bash
lizard --help --json                # full command tree + exit codes
lizard <cmd> --help --json          # a specific command's schema
```

See [JSON & Automation](https://lizard.build/docs/cli/json).

## Bootstrapping in an agent

A typical agent flow:

1. **Load the guide:** `lizard skills get core --json` → read `content`.
2. **Check auth optimistically:** run the user's task; on exit code `2`, run `lizard login`, hand the printed URL to the user, then retry.
3. **Resolve context before mutating:** `lizard status` (cwd link) and `lizard ps --json` (services).
4. **Act** using the guide — `add`, `up`, `secrets`, `domain`, etc., always with `--json`.

If the `lizard` binary isn't present, install it first:

```bash
npm install -g @lizard-build/cli
```

## Conventions agents should follow

- **Always pass `--json`** on non-interactive calls.
- **Confirm destructive actions** (delete service, drop addon, overwrite a project-wide secret, prod restart) with the user — the CLI's own prompts only fire on a TTY.
- **Scope secrets to the consuming service** by default; reserve `--global` for provably-public values. See [Variables & Secrets](https://lizard.build/docs/variables#scoping).
- **Don't write Dockerfiles unsolicited** — lizardpack auto-detects most stacks. Try a deploy first. See [Build Pipeline](https://lizard.build/docs/concepts/build-pipeline).
- **Don't use `lizard up` to switch a git-backed service to upload** — use `service set` + `redeploy`.

## Editor integrations

Lizard Skill is distributed as a public bootstrap so agents in editors and assistants can install and load it on demand, then drive the same CLI described throughout these docs. The CLI is the single source of truth — there's no separate agent API to learn.

That covers the AI IDEs too: they write and test an app but don't host it. See [deploying an app built in Google Antigravity](https://lizard.build/blog/google-antigravity-how-to-deploy-your-app-to-production#deploy-an-antigravity-app-to-production-without-typing-a-command), where the whole deploy runs from two prompts.

## See also

- [`lizard skills`](https://lizard.build/docs/cli/skills) — the full command reference.
- [JSON & Automation](https://lizard.build/docs/cli/json) — `--json` output and schema discovery.
- [Variables & Secrets](https://lizard.build/docs/variables#scoping) — secret-scoping conventions agents should follow.
- [Deploy your app from Claude Code](https://lizard.build/blog/deploy-from-claude-code#deploy-from-claude-code-in-3-steps) — the same bootstrap written as a walkthrough, with the prompts that drive it.

## Hosting your own MCP server

An agent using Lizard CLI and an application exposing MCP are separate workflows. The CLI commands above do not provide an MCP transport. To deploy your own server with Streamable HTTP, follow the [remote MCP guide](https://lizard.build/docs/guides/deploy-mcp-server).