npm create avocado-site
Bootstraps a project. This is the first command almost everyone runs.
A key is written only when it is named, with the flag or with
AVOCADO_SETUP_API_KEY. An ANTHROPIC_API_KEY exported in your shell is left
alone, because the scaffold is about to become a git repository. Unattended runs
never start the dev server; they print the command instead. A run with no
terminal and no directory name exits 1 and names the flag that fixes the call.
npm run dev.
Somebody who has typed a name has already answered the only question that
mattered.
With no argument it asks which of two jobs you want first, then the
directory name:
Interactive setup offers to take an API key, and Enter skips it — worth taking
then rather than later, because keys are read at startup, so one pasted during setup is live
immediately while one added afterwards needs a file edit and a restart.
Ports are chosen at scaffold time from what is actually free on your machine,
starting at 3000 for the site and 4100 for the editor.
→ Try the demo
npx @avocadostudio-ai/skills
The package’s command is avocado-skills.
Installs Avocado’s agent skills into a project that already exists, and nothing
else — no routes, no config, no dependencies, no prompts.
Five skills land:
avocado routes, and avocado-integrate, avocado-demo,
avocado-blocks and avocado-cms do the work.
Skill files are replaced on re-run. That is how an upgrade delivers new
instructions — never clobbering them would leave 0.13’s guidance on disk under
an 0.14 install, with nothing saying so. Every file’s outcome is reported, so a
skill you had edited shows as
updated rather than changing silently.
AGENTS.md and CLAUDE.md are yours and are only ever created.
→ Hand it to your own coding agent
avocado-scope
Reads a live page and reports what it would become as Avocado blocks, before
you install anything.
@avocadostudio-ai/migration-sdk, so npx needs the
-p to know where to find it: there is no package called avocado-scope, and a
bare npx avocado-scope answers with a 404 from the registry. Only inside a
project that already has migration-sdk installed is npx avocado-scope <url>
enough.
--allow-localhost:
A refusal explains itself in the page’s terms rather than the schema’s — “Hero
needs a link to use as its call to action” — because that is a fact about your
page, and it is more useful than either inventing a button or failing silently.
If more than half the page comes back as
RichText, the report says so.
That means the structure did not survive, and it is usually a sign the page’s
sections are worth declaring as your own block
types rather than mapped onto the built-ins.
The updatedAt on the proposed page is a deliberate placeholder — stamp it when
you decide to keep the result. Scoping is a read, and a mapper that reads a
clock is not deterministic.
Ships inside @avocadostudio-ai/migration-sdk.
avocado-studio
The self-host launcher for the editor UI, from @avocadostudio-ai/cli. It
serves a prebuilt editor bundle against a running orchestrator.
avocadostudio is an alias and is not going away. The command was renamed
so that the commands share one avocado- prefix. It was the only one that did
not.
Both names install and point at the same entry.start. avocado-studio --help, and
start --help, print the options and the other Avocado commands.
--draft-secret is required for editing a site running in production; it must
match the site’s DRAFT_MODE_SECRET. It is written into the editor’s page only
on a loopback --host. On a public bind the page is readable before sign-in, so
the CLI leaves the secret out, and the editor fetches it from the orchestrator’s
GET /editor/credentials once signed in. To host the editor publicly, give the
orchestrator DRAFT_MODE_SECRET and an access password instead. On start the CLI probes the orchestrator’s
/health and warns when the reported protocol version does not match the editor
build it ships.
avocado-register
Registers a site with an orchestrator so it appears in the editor’s Sites
list, rather than relying on defaults. Ships inside @avocadostudio-ai/site-sdk.
It works out the framework and writes the file that framework reads: on Next,
.env.local with DRAFT_MODE_SECRET, ORCHESTRATOR_URL and the
NEXT_PUBLIC_* names the scaffolds use; on Astro and anything else, .env with
DRAFT_MODE_SECRET, ORCHESTRATOR_URL and AVOCADO_SITE_ID. Only missing keys
are added. Its next steps use the project’s own package manager, from the
packageManager field or the nearest lockfile.
That file holds the draft secret, so the command also checks that git will
leave it out of a commit — with git check-ignore inside a repository, and
against the project’s .gitignore outside one — and prints the line to add
when it would not. A starter kit’s .gitignore often lists .env and not
.env.local, or neither.
The secret is checked before it is written. POST /sites/register answers
whether the secret it was sent matches the orchestrator’s DRAFT_MODE_SECRET —
match, mismatch or unset, never the value. On a mismatch the command
writes nothing and exits 1, because a site holding a secret the editor will
never send shows published content in the preview — the single most common
integration failure, and one that degrades to “the preview shows published
content” rather than an error. The fix it prints is --secret <value>, with
the value from DRAFT_MODE_SECRET in the orchestrator’s .env, which the
editor reads as VITE_SITE_DRAFT_SECRET. An explicit --secret replaces a
different value already in the env file. An orchestrator it cannot reach
leaves the env file written, the secret unchecked, and the exit code 0.
The same command is npx avocado register, or
npx @avocadostudio-ai/site-sdk register from outside the project.
avocado qa
Checks an integration the way the editor will use it, and exits non-zero when
any check fails. Ships inside @avocadostudio-ai/site-sdk as the avocado bin.
Run it from the site’s directory with the site’s dev server up.
avocado name on npm belongs to an unrelated package, so
npx avocado qa finds this command only where the SDK is installed. The scoped
form works anywhere.
It renders every page in a frame on the editor’s origin, from a throwaway
qa-<timestamp> session seeded with the site’s pages, never your own session.
Exit codes: 0 when nothing failed, 1 when a check failed, 2 for a usage error.
Warnings do not fail it. The common options:
npx avocado qa --help lists the rest. It writes .avocado/qa-report.json,
which you should not commit, and .avocado/manifest.lock, which you should.
Playwright is used when it can be found and is not a dependency. See
QA.
avocado-mcp and avocado-mcp-http
The MCP server, over stdio and streamable HTTP
respectively, from @avocadostudio-ai/mcp-server:
The packages
Twelve packages publish to npm, all versioned together.
Import from the published specifier, never a deep path into
dist or src.
Anything deeper than a documented subpath is internal and will not resolve. If
you find yourself needing one, that is a gap in the contract worth reporting
rather than routing around.
Native dependencies
orchestrator-core carries better-sqlite3 and sharp. A bundler has to be
told to leave them alone, and serverExternalPackages on its own is not enough
because transpilePackages overrides it for a transitive dependency. Wrapping
your Next config sets all of it together:
better-sqlite3 binaries ship for linux-x64 (glibc 2.28+), darwin-arm64
and darwin-x64 on Node 22. A custom Dockerfile needs python3, make and g++
on the build stage only when no prebuild matches your target.