CLI reference

The SDK ships a command-line tool, neurosquad-card. It needs only Node.js 18.17+ — no other dependencies. Run it without installing:

npx @neurosquad/card-sdk <command>

or, in a project that has @neurosquad/card-sdk installed (the React template does), npx neurosquad-card <command>. --help lists everything, --version prints the SDK version.

create

neurosquad-card create <folder> [--template vanilla|react] [--name <slug>] [--display-name <text>] [--force]

A new card from a template.

dev

neurosquad-card dev [folder] [--user-data-dir <dir>] [--no-build] [--no-logs]

Links the folder into the running app with live reload and streams the card’s log.

1. Finds NeuroSquad’s data folder — %APPDATA%\NeuroSquad on Windows, ~/Library/Application Support/NeuroSquad on macOS, ~/.config/NeuroSquad on Linux, or --user-data-dir / the NEUROSQUAD_USER_DATA_DIR environment variable for another profile — and reads card-dev.json, which the app writes while developer mode is on (port and a one-time token of the local link server).
2. Asks the app to link the folder. The app shows a confirmation with the folder and the card’s name, then the usual permission dialog. dev waits up to 5 minutes for you to accept.
3. Runs your build in watch mode when package.json has one: npm run watch, else npm run build -- --watch. --no-build skips it. These are the folder’s own npm scripts — run dev only on folders you trust, or pass --no-build.
4. Streams the card’s log — card.log.*, uncaught errors, unhandled rejections — from every copy of the card. --no-logs skips it.

The app watches the folder and reloads every copy of the card on each change (its launch is reloaded). A manifest that stops validating shows its problems on the card and in your terminal. Keys: r reloads the card, q (or Ctrl+C) quits. Quitting leaves the folder linked; unlink it in Settings → Custom cards → Developer mode.

If dev says developer mode is off, turn it on in Settings → Custom cards. The link server listens only on 127.0.0.1, exists only while developer mode is on, and every link needs your confirmation in the app.

validate

neurosquad-card validate [folder] [--json] [--app-version <x.y.z>]

Runs the checks the installer runs, without installing:

• the manifest, through the app’s own validator (schema, then the semantic checks: sizes, settings, ports, tools, schemas, reserved names);
• the files: paths the installer would refuse, files over 20 MB, over 5 000 files or 100 MB in total, names that differ only by case, symbolic links (the installer skips them), a stray .tgz;
• the icon: exists, PNG or WebP by its bytes, ≤ 128 KB, square (and a note under 64×64);
• the entry page: inline <script>, inline on…= handlers and external src/href that the sandbox will block;
• nudges: no icon, no license, no description; a name or author that claims to be NeuroSquad, official or verified (the app refuses those for non-official cards).

validate and pack are safe to run on a folder someone sent you: git runs with the folder’s own hooks disabled, and the card’s text is printed with escape sequences and bidi characters removed.

Then it prints the install dialog preview — what users will be told, high risk first, with your reasons — and exits non-zero on errors. --json prints a machine-readable report; --app-version also checks minAppVersion against that version.

Install dialog preview:
Test radar (test-radar 1.0.0)
  by Acme (self-declared)
  Community code, not made or checked by NeuroSquad.
  It will be able to:
   high    Run commands in terminals connected to it
           Type and run commands in terminal cards you connect to it with an arrow — anything you could run yourself.
   high    Read files in the workspace folder
           Any file in this workspace’s project folder, including secrets stored in files like .env.
           Why: Reads the JUnit report
   low     See the agents on this canvas
           Their names, which tool they run, and whether they are working, waiting for you or finished.
  May ask later for:
   - Copy to your clipboard
  Tools for connected agents: test_radar_run_tests
  Ports: 1 in (run:ns:trigger), 2 out (failures:ns:tasks, summary:ns:markdown)

11 files, 236.7 KB (file list from the folder)
✔ valid

pack

neurosquad-card pack [folder] [--out <file.tgz>] [--dry-run] [--json] [--allow-secret-files]

validate, plus exactly what would be installed: the files git tracks and untracked files that are not ignored — what a GitHub tarball of your repository contains — with sizes and the tree hash the app records at install (a sha-256 over every file’s path and sha-256). Then it writes a reproducible <name>-<version>.tgz (or --out); --dry-run writes nothing.

pack refuses files that look like credentials — .env* (except .env.example, .sample, .template, .dist), *.pem, *.key, *.p12, *.pfx, id_rsa*, .npmrc, .git-credentials, .netrc — unless you pass --allow-secret-files, and skips anything reached through a symbolic link or junction.

file                                size
README.md                           1.4 KB
icon.png                            4.1 KB
index.html                          1.6 KB
main.js                             7.5 KB
neurosquad-card.json                1.6 KB
…
11 files, 236.7 KB unpacked, 66.2 KB packed
tree hash  8315b0d598fee984f9144bfcaa03129de8d3be56fac57a1e4925efbb7b74842d
✔ dry run: the installer would accept this package

Outside a git repository, the file list is simply the folder’s contents.

Use it before tagging a release: if a file is missing from the list (a build output you forgot to commit), users will not get it.