# CLI reference

> neurosquad-card create, dev, validate and pack — every flag, what each command checks, and how the dev link finds the app.

Source: https://docs.neurosquad.ai/en/card-sdk/cli

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

```bash
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`

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

A new card from a template.

| Flag | Meaning |
| --- | --- |
| `--template` | `vanilla` (default): HTML + JS, no build step, the SDK copied into `vendor/`. `react`: React + Vite + TypeScript. |
| `--name` | The manifest `name`. Default: made from the folder name (`My Card` → `my-card`). |
| `--display-name` | The manifest `displayName`. Default: from the name (`my-card` → `My card`). |
| `--force` | Write into a folder that is not empty. |

## `dev`

```bash
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`

```bash
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.

```text
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`

```bash
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.

```text
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.

> The tree hash is how a user — or you — can confirm that an installed card is byte for byte the
> commit it claims to be.