# Команды

В NocoBase команды используются для выполнения операций, связанных с приложениями или плагинами, прямо из командной строки. С их помощью можно запускать системные задачи, выполнять миграции или синхронизации, инициализировать конфигурации или взаимодействовать с запущенными экземплярами приложений. Разработчики могут определять собственные команды для плагинов, регистрировать их через объект `app` и затем выполнять в CLI в формате `nocobase <command>`.

## Типы команд

В NocoBase регистрация команд делится на два типа:

| Тип | Метод регистрации | Требуется ли включение плагина | Типичные сценарии |
|------|-------------------|--------------------------------|-------------------|
| Динамическая команда | `app.command()` | ✅ Да | Команды, связанные с бизнес-логикой плагина |
| Статическая команда | `Application.registerStaticCommand()` | ❌ Нет | Команды для установки, инициализации, обслуживания |

## Динамические команды

Используйте `app.command()` для определения команд плагина. Эти команды могут быть выполнены только после включения соответствующего плагина. Файлы команд следует размещать в каталоге плагина по пути `src/server/commands/*.ts`.

Пример

```ts
import { Application } from '@nocobase/server';

export default function (app: Application) {
  app
    .command('echo')
    .option('-v, --version')
    .action(async ([options]) => {
      console.log('Hello World!');
      if (options.version) {
        console.log('Current version:', await app.version.get());
      }
    });
}
```

Описание

- `app.command('echo')`: Определяет команду с именем `echo`.
- `.option('-v, --version')`: Добавляет опцию к команде.
- `.action()`: Определяет логику выполнения команды.
- `app.version.get()`: Получает текущую версию приложения.

Выполнение команды

```bash
nocobase echo
nocobase echo -v
```

## Статические команды

Используйте `Application.registerStaticCommand()` для регистрации статических команд. Они могут быть выполнены без включения плагинов и подходят для задач установки, инициализации, миграции или отладки. Регистрация происходит в методе `staticImport()` класса плагина.

Пример

```ts
import { Application, Plugin } from '@nocobase/server';

export default class PluginHelloServer extends Plugin {
  static staticImport() {
    Application.registerStaticCommand((app: Application) => {
      app
        .command('echo')
        .option('-v, --version')
        .action(async ([options]) => {
          console.log('Hello World!');
          if (options.version) {
            console.log('Current version:', await app.version.get());
          }
        });
    });
  }
}
```

Выполнение команды

```bash
nocobase echo
nocobase echo --version
```

Описание

- `Application.registerStaticCommand()` регистрирует команды до того, как приложение будет инстанцировано.
- Статические команды обычно используются для выполнения глобальных задач, не зависящих от состояния приложения или плагина.

## Command API

Объекты команд предоставляют три необязательных вспомогательных метода для управления контекстом выполнения команды:

| Метод | Назначение | Пример |
|------|------------|--------|
| `ipc()` | Взаимодействие с запущенными экземплярами приложения (через IPC) | `app.command('reload').ipc().action()` |
| `auth()` | Проверка корректности конфигурации базы данных | `app.command('seed').auth().action()` |
| `preload()` | Предварительная загрузка конфигурации приложения (выполняет `app.load()`) | `app.command('sync').preload().action()` |

Описание конфигурации

- **`ipc()`**
  По умолчанию команды выполняются в новом экземпляре приложения.
  При включении `ipc()` команды взаимодействуют с текущим запущенным экземпляром приложения через межпроцессное взаимодействие (IPC). Это подходит для команд, требующих работы в реальном времени (например, для обновления кеша или отправки уведомлений).

- **`auth()`**
  Проверяет доступность конфигурации базы данных перед выполнением команды.
  Если конфигурация базы данных неверна или соединение не удалось, команда не будет продолжена. Часто используется для задач, связанных с записью или чтением из базы данных.

- **`preload()`**
  Предварительно загружает конфигурацию приложения перед выполнением команды, что эквивалентно вызову `app.load()`.
  Подходит для команд, которые зависят от конфигурации или контекста плагина.

Дополнительные методы API см. в разделе [AppCommand](/api/server/app-command).

## Распространенные примеры

Инициализация данных по умолчанию

```ts
app
  .command('init-data')
  .auth()
  .preload()
  .action(async () => {
    const repo = app.db.getRepository('users');
    await repo.create({ values: { username: 'admin' } });
    console.log('Initialized default admin user.');
  });
```

Перезагрузка кеша для запущенного экземпляра (режим IPC)

```ts
app
  .command('reload-cache')
  .ipc()
  .action(async () => {
    console.log('Requesting running app to reload cache...');
  });
```

Статическая регистрация команды установки

```ts
Application.registerStaticCommand((app) => {
  app
    .command('setup')
    .action(async () => {
      console.log('Setting up NocoBase environment...');
    });
});
```