CLI Commands

The ARCY CLI is included in @arcyai/sdk. Install it globally once and the arcy command is available anywhere:

bash

npm install -g @arcyai/sdk

bash

pnpm add -g @arcyai/sdk

bash

bun add -g @arcyai/sdk

bash

yarn global add @arcyai/sdk

Command	What it does
`arcy init`	First-time setup: scan codebase, wire up ARCYProvider, add data-arcy anchors, generate `.arcy/` knowledge graph
`arcy sync`	Rescan after code changes: expand anchor coverage and update `.arcy/` YAML files
`arcy push`	Push local `.arcy/` knowledge graph to your ARCY app
`arcy pull`	Pull latest knowledge graph from your ARCY app into local `.arcy/` files
`arcy validate`	Validate `.arcy/` YAML files against ARCY schemas. Exits 1 on any error. Runs automatically before `arcy push`.
`arcy status`	Show connectivity and sync state
`arcy log`	Show push history
`arcy rm`	Remove ARCY setup from the codebase

arcy init

arcy init scans your codebase, wires up ARCYProvider, adds data-arcy attributes to key UI elements, and generates the .arcy/ Application Knowledge Graph: the structured YAML files ARCY uses to understand your product.

bash

arcy init

Before writing any files, the CLI shows a full preview and asks for confirmation.

Options

Flag	Description
`--public-key <key>`	Your ARCY publishable key. Read from `.env` if not passed.
`--private-key <key>`	Your ARCY secret key. Read from `.env` if not passed.
`--dir <path>`	Directory to scan. Defaults to the current directory.
`--scan-preview`	Show files that would be analyzed, then exit without running.

Generated files

arcy init creates a .arcy/ directory with YAML files:

File	Purpose
`.arcy/app.yaml`	Root layer: app overview, personas, terminology, navigation, feature flags
`.arcy/routes/<slug>.yaml`	One file per important page with sections, actions, and common questions
`.arcy/entities/<slug>.yaml`	Core domain entities (Project, Team, Invoice, etc.)
`.arcy/journeys/<slug>.yaml`	Key user journeys (onboarding, upgrade, invite-team, etc.)

Review the generated files and expand any sections that need more detail. Run arcy push to deploy.

Privacy

arcy init reads your source files and analyzes them to generate the knowledge graph. Up to 30 files are sent (layouts, pages, key components), capped at 120KB total. Config files (.env, *.pem, *.key) are always excluded.

Before anything is transmitted, the CLI lists every file it will send and asks for your confirmation. Type n to cancel. Nothing is sent and no files are changed.

ARCY AI does not store your files or use them for data training. See What arcy init reads and sends for the full breakdown.

arcy sync

arcy sync rescans your codebase after code changes: it updates data-arcy anchors on any new or changed interactive elements and expands your .arcy/ knowledge graph with any new routes or entities detected.

Run this when you add new pages, components, or interactive elements and want the AI to know about them.

bash

arcy sync

After syncing, run arcy push to deploy the updated knowledge graph to your ARCY app.

Options

Flag	Description
`--public-key <key>`	Your ARCY publishable key. Read from `.env` if not passed.
`--private-key <key>`	Your ARCY secret key. Read from `.env` if not passed.
`--dir <path>`	Directory to scan. Defaults to the current directory.
`--dry-run`	Preview changes without writing any files.

arcy push

arcy push reads your local .arcy/ directory and pushes all YAML files to your ARCY app.

bash

arcy push

Run this after arcy init, arcy sync, and any time you edit the .arcy/ files manually. Changes are served to the SDK on every session.

Options

Flag	Description
`--dir <path>`	Root directory of the app. Defaults to the current directory.

arcy pull

arcy pull fetches the latest knowledge graph from your ARCY app and writes it into your local .arcy/ directory.

bash

arcy pull

Use this when working across multiple machines or to sync a knowledge graph that was updated remotely.

Options

Flag	Description
`--dir <path>`	Root directory of the app. Defaults to the current directory.

arcy status

arcy status shows whether your app has synced config and whether it is receiving live sessions.

bash

arcy status

Output

  ARCY AI — arcy status

  Fetching status
  ──────────────────────────────────────────────────
  ✓ Connected

    Sync:        synced (Apr 24, 2025, 02:31 PM)
    Sessions:    47 (last: Apr 24, 2025, 08:12 AM)
    Live:        no recent session

Field	Description
Sync	Whether `arcy push` has run. Shows the timestamp of the last push.
Sessions	Total session count and timestamp of the most recent session.
Live	Green if a session was received in the last 5 minutes.

Pass --wait to poll until the first session arrives, then exit automatically:

bash

arcy status --wait

Options

Flag	Description
`--dir <path>`	Root directory of the app (for reading `.env`). Defaults to current directory.
`--wait`	Poll until the first live session is received, then exit.

arcy log

arcy log shows the full history of push runs, newest first.

bash

arcy log

Sample output

  ARCY AI — push log

  #5  Apr 25, 2025  2:14 PM  ·  4.2 KB

  #4  Apr 23, 2025  11:07 AM  ·  3.9 KB  knowledge graph updated

  #3  Apr 20, 2025  6:32 PM  ·  3.1 KB

  5 pushes total

Options

Flag	Description
`--limit <number>`	Number of entries to show. Defaults to 20.
`--oneline`	One compact line per entry.
`--dir <path>`	Root directory of the app. Defaults to current directory.

arcy rm

arcy rm reverses arcy init. It removes ARCY-related code from your existing files (ARCYProvider wrapper, data-arcy attributes, SDK imports), deletes files and directories that ARCY created (.arcy/, .arcy-manifest.json), removes @arcyai/sdk from package.json, and deletes the app from your ARCY account.

bash

arcy rm

Before making any changes, the CLI shows a preview. Files ARCY modified (like your layout.tsx) are surgically cleaned using local pattern matching. No source code leaves your machine during this step. Files ARCY created (like .arcy/) are deleted.

Options

Flag	Description
`--dir <path>`	Directory to scan. Defaults to the current directory.
`--dry-run`	Preview what would change without making any changes.

After removing

Run your package manager's install command to clear the dependency from node_modules:

bash

npm install

bash

pnpm install

bash

bun install

bash

yarn install

CLI Commands

On this page