CLI reference

The areca command comes with @areca-cms/site-sdk. It connects your site project to Areca: it creates the setup files, sends your content definitions to the CMS, and pulls published content for your build. Run it from the root of your site project, through your package manager (pnpm exec areca or a package.json script).

For a walkthrough, see Installation and Pulling content.

CommandsCopy Anchor Link

Run areca with no arguments, or areca --help, to print the usage text.

Global behaviorCopy Anchor Link

These rules apply to every command.

• Environment files load first. Before any command runs, areca reads .env.local, then .env, from the current directory. A variable that is already set in the shell is never overwritten. Because .env.local loads first, it wins over .env.
• Empty values count as set. If .env.local contains ARECA_SITE_TOKEN=, that empty value blocks a value for the same key in .env.
• Empty arguments are ignored. Empty strings in the argument list are dropped before parsing.
• Errors go to stderr. A parse error prints the message and the full usage text to stderr and exits with code 1. A runtime error prints only its message to stderr.
• --help works only as the first argument. areca --help and areca -h print usage. areca pull --help fails with Unknown argument: --help.
• Unknown flags fail. Any argument a command does not recognize fails with Unknown argument: <arg>.
• A flag needs a value. The value is the next argument. If it is missing, or starts with -, the command fails with Missing value for <flag>. For example, --token -abc is rejected.

Environment file formatCopy Anchor Link

.env.local and .env are read line by line:

• Blank lines and lines starting with # are skipped.
• Each line is split at the first =. Spaces around the key and at the ends of the line are removed. Spaces inside the value are kept.
• Matching double or single quotes around a value are removed.
• There is no export prefix support, no escape handling and no inline comments.
• If a key appears twice in one file, the last value wins.

areca initCopy Anchor Link

Sets up a site project for Areca. It writes the config file, an example env file, the local env file, and a generated content folder. It also adds two scripts to package.json.

areca init --cms-url https://cms.example.com --site-key acme-site

Run init in a terminal and omit --token. The command then prompts for the site token, which is masked. Only pass --token in a script where the value comes from a secret store.

Interactive mode runs when --yes is not set and stdin is a terminal. The command prompts for each value you did not pass as a flag. After the site key it asks whether to download media into the repo (default yes) and which folder to use (default public/areca). For a folder outside public/ it also asks for the URL path that serves it. See local media.

Non-interactive mode runs otherwise. All three of --cms-url, --token and --site-key are then required.

Files writtenCopy Anchor Link

Paths are relative to the current directory.

init must run in a folder with a package.json object. Otherwise it stops before writing anything.

Environment variablesCopy Anchor Link

init does not read ARECA_* variables from the shell. It takes its values from flags or prompts, then writes them to .env.local. Variables from .env.local and .env are still loaded first.

QuirksCopy Anchor Link

• --token leaves the secret in your shell history and process list. The value appears in your command history and in ps output while the command runs. Use the prompt instead. The SDK never prints the token.
• .env.local keeps the default file permissions. On a shared machine, other users may be able to read the token. See restrict the file permissions.
• Symlinks are followed. init writes through a symlinked config or env file.

areca pullCopy Anchor Link

Downloads the current publication from the CMS and writes one JSON file per collection. It also copies every image and file the content uses into your project, and points the content at those copies, so the built site never requests anything from the CMS. Your build reads these files. Run it before dev or build, and again whenever you publish.

areca pull --out src/generated/content

The media settings come from assets in the config file: by default files go to public/areca and the content uses /areca/<file>. See local media.

The generated module is described in typed content.

Environment variablesCopy Anchor Link

OutputCopy Anchor Link

On success it prints one line, for example:

Pulled publication pub_1 (abc123): articles=1, pages=0
Media: 12 file(s) in public/areca (3 downloaded)
Types: src/generated/content/areca.gen.ts

The counts use the camelCase collection keys, so a config key blog-posts prints as blogPosts. The Types: line shows where areca.gen.ts was written. Warnings, such as the one for a publication without an embedded schema, go to stderr after it.

The folders then contain:

src/generated/content/
  areca.gen.ts                   the types and the content object (commit this)
  manifest.json                  points at the current generation
  .publications/
    publication-Ab12Cd/
      articles.json              the entries of the articles collection
      pages.json                 one file per collection
      .assets.json               the media files this generation uses
public/areca/
  hero-banner-3f2a91c0.jpg       one file per image or uploaded file

manifest.json has this shape:

{
  "publicationId": "pub_1",
  "hash": "abc123",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "collections": { "articles": 1, "pages": 0 },
  "generation": "publication-Ab12Cd",
  "assets": { "publicPath": "/areca", "count": 12 }
}

Each collection file is an array of entries. See Pulling content for the shape of an entry.

QuirksCopy Anchor Link

• Each pull is a new generation. Files are written to a new folder under .publications, then manifest.json switches to it in one rename. A failed pull leaves the previous content in place.
• Two older generations are kept. The current generation and the two before it stay, so a server that read an older manifest.json keeps working. Older generations are deleted, along with media files that only they used. Files in the media folder that no generation recorded, such as your own, are never deleted.
• Media is all or nothing. If any file fails to download, the pull fails and nothing changes. Files already on disk are not downloaded again. The media folder must be inside the project.
• Cleanup does not fail a pull. Old generations are removed after the new one is live. If that fails, the pull still succeeds and prints a warning.
• Older CMS versions. If the CMS does not list media files, the pull prints a warning and keeps the CMS URLs.
• Collection names must be safe identifiers. pull refuses a collection whose key is not a safe identifier, before it writes any file. See identifier rules.
• Entries are checked against the schema. pull checks every entry before it writes any file, and it refuses names that collide in camelCase. See what the pull checks.
• Types follow the content. areca.gen.ts is written after the new content is live. If the pull fails, the types stay as they were.
• No publication, no output. If the site has never gone live, the command fails with the 404 message and writes nothing new. See Errors and limits.

areca manifest pushCopy Anchor Link

Sends the content definitions in your config file to the CMS. The CMS then creates or updates the collections for the site. Run it after you change areca.config.ts.

areca manifest push
areca manifest push ./areca.config.ts

The command loads the config file by importing it. That runs the file's code. Keep the config free of side effects.

For a TypeScript config, the command uses Node's native TypeScript import. If that import fails, the error suggests running the command through tsx, for example pnpm exec tsx ./node_modules/@areca-cms/site-sdk/dist/cli.js manifest push ./areca.config.ts.

Environment variablesCopy Anchor Link

The schema token is in Settings › Developer for the site. Keep it on the machine where you edit the schema. It should not be in a build's environment.

Removing fieldsCopy Anchor Link

A field that still holds content cannot be removed silently. When a push would remove one, the CMS refuses it and the command lists each field with the number of entries that hold content for it:

This push removes fields that still hold content:
  - articles.subtitle: 3 entries lose this field's content

Then the command:

• On a terminal, asks Delete the content of articles.subtitle and push?, with No as the default.
• Without a terminal, stops and tells you to re-run with --confirm-drop articles.subtitle for each field, or with --yes.
• With --yes, or with each field passed to --confirm-drop, pushes and deletes that content from every stored version of the entries, including translations.

Declining, or leaving a field unconfirmed, stops the command with an error and a non-zero exit code. Nothing is pushed. Fields that hold no content are removed without asking.

OutputCopy Anchor Link

Synced manifest from ./areca.config.ts

QuirksCopy Anchor Link

• Collections missing from the file are turned off. A push turns off any collection in the CMS that the file does not define. Turned-off collections are not deleted, but their entries stop going live until the collection is turned on again.
• The payload is checked before sending. Duplicate field keys and unsafe identifiers fail in the SDK before any request is made.

areca manifest pullCopy Anchor Link

Reads the content definitions from the CMS and writes them into your config file. Use it when someone changed a content type in the CMS and you need to match it in code.

areca manifest pull
areca manifest pull --config ./areca.config.ts --yes

BehaviorCopy Anchor Link

1. The command fetches the content definitions from the CMS.
2. If the config file exists, it loads it. The site key is taken from that file.
3. The review lists the changes: collections and site content sections (+ added, ~ changed, - removed), and site languages (+ language fr added, - language de removed, ~ main language nl -> en for a new main language). A change to languages alone is listed too.
4. If the file already matches the CMS, the command writes nothing and prints areca.config.ts is already up to date.
5. Additions and changes apply without a question: new collections and fields, changed labels, types or options, and added languages. The review lists them.
6. Removals need confirmation. A removal is a collection, a site content section, a field, a language, or a changed main language. The answer defaults to No.
   • In a terminal, the command asks, for example, Remove field subtitle from articles. Continue?.
   • Without a terminal, the command fails, names what would be removed, and asks you to re-run with --yes. It writes nothing.
7. The command writes the config file. It does not keep comments or helper code.

The first line of a generated file is // Generated by `areca manifest pull` . That line marks the file as the pull's own. A file without it (hand-written, or from areca init with collections) still asks before a populated config is replaced, even when nothing changed.

A config file that defines no collections is overwritten without a prompt, even if it contains comments or helper code.

Environment variablesCopy Anchor Link

OutputCopy Anchor Link

Wrote ./areca.config.ts with 2 collection(s) (+1 ~0 -0)

If you decline a prompt, the command prints Aborted and exits with 0. A refusal without a terminal exits with a non-zero code and writes nothing.

QuirksCopy Anchor Link

• --config can point outside the project. The file is written wherever the path points. Loading the existing config also runs it.
• Writes follow symlinks. The file is written with no symlink check.

areca sync-manifestCopy Anchor Link

A deprecated alias of areca manifest push. It takes the same optional [config] argument and has the same behavior, environment variables and output. Use manifest push in new scripts. The alias is kept so that existing package.json scripts keep working.

areca runCopy Anchor Link

Runs any other command with the environment loaded from .env.local and .env. Use it to start your dev server with Areca variables present.

areca run -- vite --port 3001

The arguments after -- form the command. The -- is required, and at least one argument must follow it. Otherwise the command fails with Missing command. Usage: areca run -- <command>.

BehaviorCopy Anchor Link

• The command runs in a shell with inherited input and output. It exits with the child's exit code.
• If the child is stopped by a signal, areca run exits with 1.
• If the command cannot start, the error is printed and areca run exits with 1.

QuirksCopy Anchor Link

• Arguments are joined into one string. The words are joined with spaces and passed to the shell. Quoting is lost. An argument that contains a space must be quoted in your shell, and then it is passed through as typed. Keep commands simple, or put complex commands in a package.json script.
• Environment variables stay with the child process. The variables are passed to the command you run. They are not exported to your shell.

Exit codesCopy Anchor Link

Cancelling init exits with 0 and prints Operation cancelled. That is easy to miss in a script. Pass --yes and all three values when you script init.

Environment variablesCopy Anchor Link

Areca's deployments also set ARECA_SNAPSHOT_ID as a Docker build argument, which changes on every release and so stops Docker from reusing an older pull. See Go-live builds.

For the CMS's own environment variables, see Configuration.

RelatedCopy Anchor Link

• Installation walks through areca init.
• Schema sync explains when to run manifest push and manifest pull.
• Pulling content explains the output of areca pull.
• Errors and limits lists the messages these commands print.