CLI and packages - Avocado Studio

Six commands and twelve packages. Until now they were documented wherever they happened to be used; this is the list.

`npm create avocado-site`

Bootstraps a project. This is the first command almost everyone runs.

npm create avocado-site@latest my-site

It takes one positional argument — the directory — and no flags. With a directory name it goes straight to the demo: a runnable Next.js project with the Avocado Hub’s nine pages in it, the orchestrator mounted inside the app in library mode, and the editor served alongside by one 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:

Mode	What it does
Demo	Creates a new project and installs it
Integrate	Writes the wiring into a Next.js app that already exists, then tells you what is left to do. Both modes also write the agent skills below

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`

Installs Avocado’s agent skills into a project that already exists, and nothing else — no routes, no config, no dependencies, no prompts.

npx @avocadostudio-ai/skills

This is the fastest way to start an integration: your coding agent reads instructions that match the version you are installing, instead of a prompt pasted from a page that cannot be versioned against npm.

Written
`.claude/skills/`	For Claude Code
`.agents/skills/`	For the cross-agent `skills` CLI — Cursor, Codex, Gemini
`AGENTS.md`	Only if absent. Yours is never overwritten
`CLAUDE.md`	Only if absent

Four skills land: avocado routes, and avocado-integrate, avocado-demo and avocado-blocks do the work.

Option
`[directory]`	Where to write. Defaults to the current directory
`--dry-run`	Print what would be written, write nothing

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

`npx avocado-scope`

Reads a live page and reports what it would become as Avocado blocks, before you install anything.

npx avocado-scope https://example.com/about

https://example.com/about
9 sections found, 9 mapped to blocks.

section  becomes          note
0        CTA              was Hero — Hero needs an image with alt text
1        FeatureGrid
5        RichText         was FeatureGrid — needs two sub-headings each followed by a paragraph
7        FAQAccordion

Result: CTA×1, FeatureGrid×3, RichText×4, FAQAccordion×1

It answers the question every adopter asks first — what would my site look like in Avocado — with no orchestrator, no session, no site, no API key and no model. Read-only and deterministic: nothing is written, and the same page always gives the same answer, so re-running it after a change is a diff rather than a new opinion.

Option
`--allow-localhost`	Permit local and private addresses. Off by default, because this fetches whatever URL it is given
`--json`	Also print the proposed `PageDoc`

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 all five commands share one prefix — it was the only one that did not. Both names install and point at the same entry.

npx @avocadostudio-ai/cli start \
  --orchestrator http://localhost:3000/api/avocado \
  --preview      http://localhost:3000

It has exactly one command, start:

Flag	Environment variable	Default
`--orchestrator <url>`	`AVOCADO_ORCHESTRATOR_URL`	`http://localhost:4200`
`--preview <url>`	`AVOCADO_SITE_ORIGIN`	`http://localhost:3000`
`--publish-token <token>`	`AVOCADO_PUBLISH_TOKEN`	—
`--draft-secret <secret>`	`AVOCADO_SITE_DRAFT_SECRET`, then `DRAFT_MODE_SECRET`	—
`--port <n>`	`PORT`	`4100`
`--host <addr>`	`HOST`	`127.0.0.1`

The default --orchestrator is the standalone server’s address and is wrong for library mode. If your orchestrator runs inside your Next.js app, pass --orchestrator http://localhost:3000/api/avocado explicitly. Forgetting it is the usual cause of “the preview shows the published page and never my edits”.

HOST is read from the environment, and container platforms set it for you. If the editor binds somewhere you did not ask for, that is why — pass --host explicitly to override it.

--draft-secret is required for editing a site running in production; it must match the site’s DRAFT_MODE_SECRET. 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.

npx avocado-register --name "Marketing Site" \
  --orchestrator http://localhost:3000/api/avocado

Run it from the project directory. Most of what it needs it can work out:

Flag	Default
`--name <string>`	the project’s `package.json` name
`--id <kebab-case>`	kebab-case of `--name`
`--port <number>`	parsed from `scripts.dev` in `package.json`, else `3000`
`--orchestrator <url>`	`$ORCHESTRATOR_URL`, then `.env.local`’s value
`--secret <string>`	read from `.env.local`, or generated
`--session <string>`	`dev`
`--preview-url <url>`	`http://localhost:<port>`
`--purpose <string>`	— (a one-line site description, used as AI context)
`--token <string>`	`$ORCHESTRATOR_ACCESS_TOKEN`
`--cwd <path>`	the current directory

It also generates a DRAFT_MODE_SECRET into .env.local when there is not one, and warns when the editor’s copy of that secret does not match the site’s — the single most common integration failure, because it degrades to “the preview shows published content” rather than an error.

`avocado-mcp` and `avocado-mcp-http`

The MCP server, over stdio and streamable HTTP respectively. AVOCADO_MCP_PORT and AVOCADO_MCP_BEARER_TOKEN configure the HTTP transport.

The packages

Twelve packages publish to npm, all versioned together.

Package	What it is
`@avocadostudio-ai/site-sdk`	The integration surface. Routes, the page factory, markers, publishing, block registration, library mode. The one you install.
`@avocadostudio-ai/orchestrator-core`	The brain — session state, AI planning, the operations engine, publishing. An optional peer of the SDK, so it is not installed for you; library mode needs it.
`@avocadostudio-ai/blocks`	The built-in React block renderers and their stylesheet
`@avocadostudio-ai/shared`	Zod schemas — `PageDoc`, `BlockInstance`, `Operation` — and the block registry
`@avocadostudio-ai/preview-adapter`	The preview bridge and the editor overlay
`@avocadostudio-ai/richtext`	The rich-text grammar, and converters for four CMSes
`@avocadostudio-ai/astro`	The Astro integration
`@avocadostudio-ai/cli`	The `avocadostudio` launcher above
`@avocadostudio-ai/mcp-server`	The MCP server
`@avocadostudio-ai/migration-sdk`	Utilities for migrating existing content into `PageDoc` shape
`@avocadostudio-ai/skills`	The agent skills above. Also the source `create-avocado-site` writes them from
`create-avocado-site`	The scaffolder above

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:

import { withAvocado } from "@avocadostudio-ai/site-sdk/next-config"
export default withAvocado({ /* your config */ })

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

​npm create avocado-site

​npx @avocadostudio-ai/skills

​npx avocado-scope

​avocado-studio

​avocado-register

​avocado-mcp and avocado-mcp-http

​The packages

​Native dependencies

`npm create avocado-site`

`npx @avocadostudio-ai/skills`

`npx avocado-scope`

`avocado-studio`

`avocado-register`

`avocado-mcp` and `avocado-mcp-http`

The packages

Native dependencies