> ## Documentation Index > Fetch the complete documentation index at: https://docs.avocadostudio.dev/llms.txt > Use this file to discover all available pages before exploring further. # CLI and packages > The six commands Avocado ships, every flag each one takes, and what each of the twelve published packages is for. 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. ```bash theme={null} 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](/first-run) ## `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. ```bash theme={null} 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](/sites/coding-agent) ## `npx avocado-scope` Reads a live page and reports what it would become as Avocado blocks, before you install anything. ```bash theme={null} 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](/integration/custom-blocks) 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. ```bash theme={null} 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 ` | `AVOCADO_ORCHESTRATOR_URL` | `http://localhost:4200` | | `--preview ` | `AVOCADO_SITE_ORIGIN` | `http://localhost:3000` | | `--publish-token ` | `AVOCADO_PUBLISH_TOKEN` | — | | `--draft-secret ` | `AVOCADO_SITE_DRAFT_SECRET`, then `DRAFT_MODE_SECRET` | — | | `--port ` | `PORT` | `4100` | | `--host ` | `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`. ```bash theme={null} 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 ` | the project's `package.json` name | | `--id ` | kebab-case of `--name` | | `--port ` | parsed from `scripts.dev` in `package.json`, else `3000` | | `--orchestrator ` | `$ORCHESTRATOR_URL`, then `.env.local`'s value | | `--secret ` | read from `.env.local`, or generated | | `--session ` | `dev` | | `--preview-url ` | `http://localhost:` | | `--purpose ` | — (a one-line site description, used as AI context) | | `--token ` | `$ORCHESTRATOR_ACCESS_TOKEN` | | `--cwd ` | 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](/integration/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](/integration/astro-integration) | | `@avocadostudio-ai/cli` | The `avocadostudio` launcher above | | `@avocadostudio-ai/mcp-server` | The [MCP server](/integration/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: ```ts theme={null} 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.