CLI Commands

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

npmpnpmbunyarn

npm install -g @arcyai/sdk

pnpm add -g @arcyai/sdk

bun add -g @arcyai/sdk

yarn global add @arcyai/sdk

arcy init

arcy init is the one-time local setup. It detects your framework and auth library, wires ARCYProvider into your app entry with a deterministic code change, installs @arcyai/sdk, and finishes by running arcy analyze once to seed the .arcy/ Application Knowledge Graph with your routes. It never mutates your JSX.

Fully supported frameworks: Next.js App Router, Next.js Pages Router, Vite + React, Create React App. Fully supported auth libraries: Clerk, NextAuth, Auth0, Supabase, Firebase. Any other combination still installs and runs arcy analyze, but init prints a manual wiring snippet instead of auto-wiring ARCYProvider.

arcy init

Everything runs on your machine. No source file is sent anywhere; the only network traffic is your own package manager installing the SDK.

Options

Running in a pnpm monorepo

If you run arcy init at the root of a pnpm workspace (a directory containing pnpm-workspace.yaml), it detects that unconditionally, before it even looks at your framework, and prompts you to pick which app to set up from the workspace's packages: globs:

This looks like a pnpm workspace root.
Which app are you setting up?
1. apps/dashboard
2. apps/landing
3. Other (enter path manually)

Everything after that (key check, framework detection, provider wiring, .arcy/ generation, install) runs scoped to the app you picked, never the workspace root. If you already know the target, skip the prompt with --dir apps/dashboard — a real app directory never itself contains pnpm-workspace.yaml, so it is unaffected either way.

How the provider is wired

arcy init writes a small arcy-provider wrapper component next to your app entry and wraps the entry's render site with it: the root layout's {children} on Next.js App Router, <Component {...pageProps} /> on the Pages Router, or <App /> in the bootstrap file (src/main.tsx for Vite, src/index.tsx for CRA). The change is a plain, reviewable edit in your working tree.

When the entry does not match exactly (for example the render site appears in more than one place, or an arcy-provider file already exists), init leaves your code untouched and prints the exact snippet to paste instead. It never guesses.

Vite and CRA only expose prefixed env vars to the client: Vite needs VITE_ARCY_PUBLISHABLE_KEY, CRA needs REACT_APP_ARCY_PUBLISHABLE_KEY, both set to the same value as your publishable key. For a local/test key, the same applies to VITE_ARCY_TEST_PUBLISHABLE_KEY/REACT_APP_ARCY_TEST_PUBLISHABLE_KEY. Init prints a reminder with the correct prefix for your framework.

The generated wrapper's live JSX stays minimal: your publishable key, showWidget={true}, and any props you pass through from your own app. Above it, a commented-out reference block shows the full prop and customization shape (theme, elements, limits, modes, content) with labeled placeholder values, plus a framework-appropriate onNavigate snippet, so you can see everything available without anything shipping as a live default you'd have to notice and change. See Configuration and Customization for the full field docs.

Re-running init

If a .arcy/ directory already exists, arcy init stops so it never overwrites edited YAML. You have two options:

• arcy analyze refreshes route detection and adds newly discovered pages without touching YAML you have edited. This is the normal way to keep navigation current.
• arcy init --force starts over. The CLI prints exactly what it is about to delete, then removes your existing .arcy/ outright and regenerates it from scratch. This is deliberately destructive: there is no backup and no undo, so make sure anything you want to keep is committed or copied out first.

Generated files

The analyze run at the end of init creates the .arcy/ directory:

Entity and flow files (.arcy/entities/, .arcy/flows/) are yours to add as your knowledge graph grows. Review the generated files, fill in descriptions, then run arcy push to deploy. Element-level context (what's on a page) is proposed automatically by ARCY's AI curation service once the SDK is live and observing real usage; see Element Targeting.

Privacy

arcy init and arcy analyze read your source files locally and never transmit them. The generated .arcy/ YAML (page structure, labels, route paths) is the only thing that leaves your machine, and only when you run arcy push. Config files (.env, *.pem, *.key) are never read.

arcy analyze

arcy analyze walks your codebase locally and deterministically: it finds your routes, seeds day-one page navigation by reading your framework's own route configuration, and generates .arcy/ knowledge graph skeletons.

It makes zero network calls. Nothing in your source code leaves your machine, and it never writes anything into your JSX. The command is non-interactive with deterministic exit codes, so it is safe to run in CI on every commit.

arcy analyze

Repeat runs are incremental: a content-hash manifest (.arcy/analyze-manifest.json) tracks every file, and only files that changed since the last run are re-analyzed, which keeps CI overhead in the seconds range.

An existing .arcy/app.yaml is never overwritten, and hand-authored content in .arcy/routes/*.yaml (help text, descriptions, sections) survives re-runs. Only the structural route.path/route.label keys are refreshed.

Options

arcy push

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

arcy push

Run this after arcy init, after arcy analyze picks up new pages or elements, and any time you edit the .arcy/ files manually. Changes are served to the SDK on every session.

The request times out after 10 seconds on a hung connection and prints a clear "Request timed out" message instead of a raw network error.

Options

arcy pull

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

arcy pull

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

The request times out after 10 seconds on a hung connection and prints a clear "Request timed out" message instead of a raw network error.

Options

arcy validate

arcy validate checks every file in your local .arcy/ directory against the ARCY YAML schemas. It runs automatically before arcy push, and you can run it on its own at any time.

arcy validate

It is local only and makes no network calls. Field-level errors are printed with the file and path (for example route.path: Required), and the command exits 1 if anything fails.

Options

arcy status

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

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

Each request times out after 10 seconds on a hung connection and prints a clear "Request timed out" message instead of a raw network error.

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

arcy status --wait

Options

arcy log

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

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

arcy rm

arcy rm reverses arcy init. It removes ARCY-related code from your existing files (the ARCYProvider wrapper, SDK imports), strips any leftover data-arcy/data-arcy-action attributes from an install predating the current fingerprint-based targeting (nothing writes these anymore, but a cleanup pass runs anyway for older installs), 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.

arcy rm

Before making any changes, the CLI shows a preview and asks you to confirm. 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.

If a file's ARCY wiring was hand-edited into a shape the cleaner cannot safely undo, that file is left completely untouched and the summary tells you to unwind it by hand. Every other file in the same run is still cleaned normally.

Options

After removing

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

npmpnpmbunyarn

npm install

pnpm install

bun install

yarn install