CLI

@mapled/cli is the mapled command. It needs Node 18 or newer and has no dependencies. Run it with npx, or install it once with npm install -g @mapled/cli and type mapled … instead of npx @mapled/cli ….

npx @mapled/cli --help

Credentials live in your user config directory (~/.config/mapled/credentials.json, readable only by you), never in the repository.

For AI agents

connect

npx @mapled/cli connect --project <id>

Signs in for the repository it runs in: the browser opens Mapled on that project and the person presses Authorize — nothing is copied or pasted. Writes mapled.json and prints Mapled's guide for agents (also at https://api.mapled.io/agents.md). Run again in a connected repository, or in a subdirectory of one, it opens no browser. Without --project the person picks the project in the browser.

tools, tool

npx @mapled/cli tools
npx @mapled/cli tool get_schema
npx @mapled/cli tool propose_setup_plan --input plan.json
npx @mapled/cli tool get_setup_run '{"runId":"…"}' --wait

tools lists every tool with its input (--json for the schemas). tool <name> calls one — the same tools the MCP server offers, through the same connection. The input is a JSON object, inline or in a file with --input; the answer is printed as Mapled worded it, and a refusal exits 1.

tool get_setup_run … --wait waits while the plan is still waiting for approval and prints the run once the person has decided — 90 seconds by default, up to 600 with --wait=<seconds>; then the agent runs it again.

Sign in and link

auth login, auth logout

npx @mapled/cli auth login
npx @mapled/cli auth logout

auth login opens Mapled in the browser: you pick the project and authorize. The CLI is an ordinary OAuth client of Mapled, so the connection shows up in the project's Integrations and can be revoked there. --no-browser prints the sign-in link instead of opening it. auth logout revokes the connection of the linked project; --all revokes every project on this machine.

project link

npx @mapled/cli project link

Writes mapled.json next to package.json — the project id, where the generated types go, the framework. Only public values; commit it. With more than one signed-in project, pass --project <id> or pick from the list.

Types and the schema

types generate

npx @mapled/cli types generate

Reads the project's schema and writes mapled-types.ts (the path from mapled.json, or --out <file>): one interface per collection and single, a MapledSchema that ties them together, and doc comments with the field types. Sensitive fields are left out. Run it again after the schema changes.

schema pull, schema diff

npx @mapled/cli schema pull
npx @mapled/cli schema diff

schema pull writes mapled/schema.json — the schema this site is built against, without ids or timestamps, so it diffs cleanly in git. schema diff compares that pin with the live schema and judges every change for a site that reads the content: breaking when something the site may rely on disappears, changes type, becomes optional or sensitive; safe for additions, labels, help texts, validation rules, and a renamed key while its old one is still an alias. --json for scripts; --exit-code exits 1 when anything changed, for CI.

The site manifest

scan

npx @mapled/cli scan
npx @mapled/cli scan --write

Reads the site's source and lists what it reads from Mapled: the pages (from the framework's file layout — Next.js, Astro, SvelteKit, Nuxt, Remix — or a plain HTML site's .html files) and one binding per place a collection or field is used. --write creates or updates mapled/manifest.json; bindings the scan can't see are kept unless you pass --prune. Source code never leaves your machine — only the manifest does, when you push it.

manifest validate

npx @mapled/cli manifest validate

Checks mapled/manifest.json the way Mapled will: the shape and limits, collections and fields that don't exist, targets that don't fit the field type, files the repository doesn't have. Problems exit 1.

bindings push, bindings pull

npx @mapled/cli bindings push
npx @mapled/cli bindings pull

bindings push sends the manifest to Mapled, which grades every binding — healthy, type mismatch, outdated, missing on site — in Structure → Bindings, and records the integration hash. --dry-run validates and stops. It changes structure, so it needs the builder plan. bindings pull writes the pushed manifest into mapled/manifest.json; it won't overwrite a local file that differs unless you pass --force.

MAPLED.md

md pull

npx @mapled/cli md pull

Writes MAPLED.md at the repository root — the guide Mapled renders from the project for whoever works on the site next: the content model, where each page renders which field, the last setup run, the working rules and the commands that verify the integration. It never contains a secret. Everything below the <!-- mapled:notes --> line is yours and survives every pull.

Forms

forms create, forms list

npx @mapled/cli forms create "Contact"
npx @mapled/cli forms list

forms create makes a form the site can post submissions to, and prints the address it posts to. The key comes from the name, or --key <key>; --no-spam-protection turns the honeypot off. It changes structure, so it needs the builder plan. forms list shows every form with the URL the site posts to.

Media

media upload

npx @mapled/cli media upload public/products/hoodie.jpg https://example.com/cover.png
npx @mapled/cli media upload --run <runId>

Puts images and files into the project's Media: a path is read from the repository (a path from the site's root, /images/a.png, is looked for under public/ and static/ too; nothing outside the repository is read), an address is downloaded by Mapled. PNG, JPEG, WebP, GIF and SVG up to 10 MB, PDF up to 25 MB; the same bytes uploaded twice are one file. Each line names the asset id an image or file field holds. --run <runId> uploads every file an approved setup plan names that isn't in Mapled yet, for apply_setup_plan to put into the records; tool apply_setup_plan does it first by itself. A file that didn't upload is named with the reason and the command exits 1.

Checks

doctor

npx @mapled/cli doctor

Checks the integration from both sides. In the repository: the link, the sign-in, the generated types, the schema pin, the manifest and the integration hash, MAPLED.md, the env variables (names only — values are never read), env files or secrets tracked by git, the installed package versions, and the revalidation, preview and release routes. In Mapled: whether the site has read content, the publish webhook's last delivery, the preview route on the deployed site, the bindings' health. Exit code 1 when something is marked ✗; --json for scripts and agents.

--load-config is for a next.config doctor can't read on its own (one that calls a plugin or loads other modules): the site's installed Next loads it in a separate process, as next build would. This runs the site's code; without the flag doctor runs nothing of the site.

integration report

npx @mapled/cli integration report

Prints the last applied AI setup run: the plan, the verification checklist, what was created, the files changed and what stays hardcoded. --verify runs the server checks again first. A site connected without an agent has no run — doctor checks it.

Preview

preview

npx @mapled/cli preview
npx @mapled/cli preview articles hello-world

Prints a one-time Preview link — the one the Preview button in Mapled opens: the site in draft mode, with every saved change that isn't published yet. Name a collection and a record's slug or id to land on the record's page. The link works once, for five minutes. --locale <code> opens the page in one of the project's languages; --open opens it in your browser.

The server key

env push

npx @mapled/cli env push --host vercel

Gives the site on Vercel, Netlify or Cloudflare (--host vercel|netlify|cloudflare) a server key of its own and sets it as MAPLED_SERVER_KEY there, without the key passing through you or your agent. Run it from the site's repository with the host's CLI signed in and linked. It prints a link an owner of the project confirms on in Mapled; then it claims the key — once, within ten minutes, only from the process that asked — and hands it to the host's CLI; a Worker with Wrangler environments takes --env <name>. The key is never printed or written anywhere; you see its prefix. Redeploy the site afterwards.

Options

• --api <origin> — a Mapled API other than https://api.mapled.io (or MAPLED_API_URL)
• --json — machine-readable output, for tools, doctor, integration report, schema diff, scan, manifest validate, forms list, preview and env push
• MAPLED_CONFIG_DIR — where credentials live
• --version, --help

Files in the repository

File	Written by	Purpose
mapled.json	connect, project link	The project id, the types path, the framework — public values only
mapled-types.ts	types generate	TypeScript types of the published content, with MapledSchema
mapled/schema.json	schema pull, types generate	The schema this site is built against
mapled/manifest.json	scan --write, bindings pull	Pages and bindings — where the code reads each collection and field
MAPLED.md	md pull	The guide for the next agent or developer

Commit all five. Never commit an env file.