# `:agentik-cli` — JVM CLI клиент к `/agentik`

## Что это

JVM-only **one-shot subcommand CLI** к серверу `:standalone` через
`:client` по HTTP+SSE. Один вызов — одна команда: стримы ответа
`send` идёт в stdout построчно, никакого embedded-REPL.

Решает: быстрый способ дёрнуть агента из shell-скрипта или руками,
не поднимая отдельную TUI-сессию.

## Подкоманды

```
agentik-cli <subcommand> [options]

Subcommands:
    conv-ls       Список диалогов агента
    conv-new      Создать диалог; печатает id
    conv-show     Метаданные диалога
    conv-delete   Удалить диалог
    conv-rename   Переименовать диалог
    msgs          Показать сообщения диалога
    send          Отправить user-ход и стримить ответ
    interrupt     Прервать текущий ход диалога
    info          Показать server URL и agent id
```

`--server URL` и `--id ID` (env: `AGENTIK_SERVER`, `AGENTIK_AGENT_ID`)
задаются **после** имени subcommand'а — kotlinx.cli не шарит опции
родителя в subcommand. Пример:

```bash
agentik-cli conv-ls --server http://192.168.76.166:8080/agentik
agentik-cli conv-new --server http://localhost:8080/agentik
agentik-cli send --server http://localhost:8080/agentik conv-abc "привет"
```

## Как запустить

### Из готового fatjar

```bash
java --enable-native-access=ALL-UNNAMED \
     -jar agentik-cli-0.1.0-SNAPSHOT-all.jar --help
```

### Через Gradle

```bash
./gradlew :agentik-cli:shadowJar
java -jar agentik-cli/build/libs/agentik-cli-0.1.0-SNAPSHOT-all.jar info
```

## Примеры

```bash
# Список диалогов (таблица)
agentik-cli conv-ls --server http://localhost:8080/agentik

# Создать диалог
ID=$(agentik-cli conv-new --server http://localhost:8080/agentik)
echo "new conv: $ID"

# Переименовать
agentik-cli conv-rename --server http://localhost:8080/agentik "$ID" "мой чат"

# Отправить ход и стримить ответ
agentik-cli send --server http://localhost:8080/agentik "$ID" "2+2"

# Показать последние N сообщений
agentik-cli msgs --server http://localhost:8080/agentik "$ID" --limit 10

# Прервать активный ход
agentik-cli interrupt --server http://localhost:8080/agentik "$ID"

# Удалить
agentik-cli conv-delete --server http://localhost:8080/agentik "$ID"
```

## Формат вывода `send`

Каждое SSE-событие печатается отдельной строкой `event <Type> ...` —
пригодно для парсинга через `awk`/`jq`-обёртки:

```
event StartReasoning
event StartResponse TEXT
event AppendText \n\n
event AppendText Привет!
event End
```

Терминальные события (`End`, `Interrupted`, `Error`) тоже
печатаются; CLI выходит сразу после `End`.

## Почему JVM-only (а не KMP)

Аргумент-парсер: `kotlinx.cli` 0.3.6 (JetBrains, KMP) — единственный
зрелый вариант, который линкуется нативно под `linuxX64`/`linuxArm64`
без upstream-багов. Альтернативы:

- **clikt-multiplatform 5.x** имеет upstream-баг: `clikt` и
  `clikt-mordant` оба объявляют `selfAndAncestors` в commonMain, и
  Kotlin/Native linker падает на дубликате символа
  (issue [ajalt/clikt#598](https://github.com/ajalt/clikt/issues/598),
  workaround — `kotlin.native.cacheKind.linuxX64=none`, что замедляет
  сборку на порядки). Поэтому clikt отвергнут в пользу kotlinx.cli.
- **picocli** — JVM-only.
- **kotlinx-args** — мёртвый репозиторий.

Нативные бинари `:agentik-cli` отложены до стабилизации
arg-parser-ситуации.

## Тесты

```bash
./gradlew :agentik-cli:jvmTest
```

## Версии

`gradle/libs.versions.toml` → `[versions] agentik-agentik-cli`.