# Справочник CLI

> neurosquad-card create, dev, validate и pack — все флаги, что проверяет каждая команда и как подключение для разработчика находит приложение.

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

В SDK есть утилита командной строки `neurosquad-card`. Ей нужен только Node.js 18.17+ — других
зависимостей нет. Запускайте без установки:

```bash
npx @neurosquad/card-sdk <command>
```

или, в проекте, где установлен `@neurosquad/card-sdk` (как в шаблоне React),
`npx neurosquad-card <command>`. `--help` перечисляет всё, `--version` печатает версию SDK.

## `create`

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

Новая карточка из шаблона.

| Флаг | Значение |
| --- | --- |
| `--template` | `vanilla` (по умолчанию): HTML + JS, без сборки, SDK копируется в `vendor/`. `react`: React + Vite + TypeScript. |
| `--name` | `name` в манифесте. По умолчанию — из имени папки (`My Card` → `my-card`). |
| `--display-name` | `displayName` в манифесте. По умолчанию — из имени (`my-card` → `My card`). |
| `--force` | Писать в непустую папку. |

## `dev`

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

Подключает папку к запущенному приложению с живой перезагрузкой и транслирует журнал карточки.

1. Находит папку данных NeuroSquad — `%APPDATA%\NeuroSquad` в Windows,
`~/Library/Application Support/NeuroSquad` в macOS, `~/.config/NeuroSquad` в Linux, или
`--user-data-dir` / переменную окружения `NEUROSQUAD_USER_DATA_DIR` для другого профиля — и
читает `card-dev.json`, который приложение пишет, пока включён **режим разработчика** (порт и
одноразовый токен локального сервера подключения).
2. Просит приложение подключить папку. Приложение показывает подтверждение с папкой и именем
карточки, потом обычный диалог разрешений. `dev` ждёт вашего согласия до 5 минут.
3. Запускает вашу сборку в режиме наблюдения, если она есть в `package.json`: `npm run watch`, иначе
`npm run build -- --watch`. `--no-build` это пропускает. **Это собственные npm-скрипты папки** —
запускайте `dev` только на папках, которым доверяете, или передавайте `--no-build`.
4. Транслирует журнал карточки — `card.log.*`, необработанные ошибки, отклонённые промисы — со всех
копий карточки. `--no-logs` это пропускает.

Приложение следит за папкой и перезагружает все копии карточки при каждом изменении (их `launch` —
`reloaded`). Если манифест перестаёт проходить проверку, проблемы видны на карточке и в вашем
терминале. Клавиши: **r** перезагружает карточку, **q** (или Ctrl+C) выходит. После выхода папка
остаётся подключённой; отключить её можно в **Settings → Custom cards → Developer mode**.

Если `dev` говорит, что режим разработчика выключен, включите его в **Settings → Custom cards**.
Сервер подключения слушает только `127.0.0.1`, существует, только пока включён режим разработчика,
и каждое подключение нужно подтвердить в приложении.

## `validate`

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

Выполняет проверки установщика без установки:

- манифест — собственным валидатором приложения (схема, затем смысловые проверки: размеры,
настройки, порты, инструменты, схемы, зарезервированные имена);
- файлы: пути, которые установщик отклонит, файлы больше 20 МБ, больше 5 000 файлов или 100 МБ в
сумме, имена, отличающиеся только регистром, символические ссылки (установщик их пропускает),
случайно оставленный `.tgz`;
- иконку: существует, PNG или WebP по содержимому, до 128 КБ, квадратная (и замечание, если меньше
64×64);
- входную страницу: встроенные `<script>`, встроенные обработчики `on…=` и внешние `src`/`href`,
которые заблокирует песочница;
- подсказки: нет иконки, лицензии, описания; имя или автор выдают себя за NeuroSquad, official или
verified (у неофициальных карточек приложение такое отклоняет).

`validate` и `pack` безопасно запускать на папке, которую вам кто-то прислал: git работает с
отключёнными хуками самой папки, а текст карточки печатается без escape-последовательностей и
символов направления текста (bidi).

Затем печатает **превью диалога установки** — что увидят пользователи, начиная с высокого риска, с
вашими объяснениями — и при ошибках завершается с ненулевым кодом. `--json` печатает отчёт для
машин; `--app-version` дополнительно сверяет `minAppVersion` с этой версией.

```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`, плюс что именно будет установлено: файлы, которые отслеживает git, и
неотслеживаемые, но не игнорируемые — то, что попадает в архив вашего репозитория на GitHub, — с
размерами и **хешем дерева**, который приложение записывает при установке (sha-256 по пути и
sha-256 каждого файла). Потом пишет воспроизводимый `<name>-<version>.tgz` (или `--out`);
`--dry-run` ничего не пишет.

`pack` отказывается упаковывать файлы, похожие на учётные данные, — `.env*` (кроме `.env.example`,
`.sample`, `.template`, `.dist`), `*.pem`, `*.key`, `*.p12`, `*.pfx`, `id_rsa*`, `.npmrc`,
`.git-credentials`, `.netrc`, — если не передать `--allow-secret-files`, и пропускает всё, до чего
можно дойти только через символическую ссылку или 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
```

Вне git-репозитория список файлов — это просто содержимое папки.

Запускайте перед тегом релиза: если какого-то файла нет в списке (например, результата сборки,
который вы забыли закоммитить), пользователи его не получат.

> Хеш дерева — это способ, которым пользователь (или вы) может убедиться, что установленная карточка
> байт в байт совпадает с тем коммитом, за который себя выдаёт.