Руководство по CLI для AIKraft Agents

Использование

craft-agent <entity> <action> [args] [--flags] [--json '<json>'] [--stdin]

Глобальные флаги

• craft-agent --help
• craft-agent --version
• craft-agent --discover

Режимы ввода

• Простые флаги для базовых значений
• --json для структурированных входных данных
• --stdin для передачи JSON-объекта через конвейер (pipe)

Лейбл

Управление лейблами workspace, хранящимися в папке labels/.

Команды

• craft-agent label list
• craft-agent label get <id>
• craft-agent label create --name "<name>" [--color "<color>"] [--parent-id <id|root>] [--value-type string|number|date]
• craft-agent label update <id> [--name "<name>"] [--color "<color>"] [--value-type string|number|date|none] [--clear-value-type]
• craft-agent label delete <id>
• craft-agent label move <id> --parent <id|root>
• craft-agent label reorder [--parent <id|root>] <ordered-id-1> <ordered-id-2> ...
• craft-agent label auto-rule-list <id>
• craft-agent label auto-rule-add <id> --pattern "<regex>" [--flags "gi"] [--value-template "$1"] [--description "..."]
• craft-agent label auto-rule-remove <id> --index <n>
• craft-agent label auto-rule-clear <id>
• craft-agent label auto-rule-validate <id>

Примеры

craft-agent label list
craft-agent label get bug
craft-agent label create --name "Bug" --color "accent"
craft-agent label create --name "Priority" --value-type number
craft-agent label update bug --json '{"name":"Bug Report","color":"destructive"}'
craft-agent label update priority --value-type none
craft-agent label move bug --parent root
craft-agent label reorder --parent root development content bug
craft-agent label auto-rule-add linear-issue --pattern "\\b([A-Z]{2,5}-\\d+)\\b" --value-template "$1"
craft-agent label auto-rule-list linear-issue
craft-agent label auto-rule-validate linear-issue

Примечания

• Используйте --json / --stdin для вложенных или пакетных обновлений.
• Идентификаторы (IDs) — это стабильные слаг-значения, генерируемые из имени при создании.
• Используйте --value-type none или --clear-value-type, чтобы удалить тип значения лейбла.

Источник

Управление источниками workspace, хранящимися в папках sources/{slug}/.

Команды

• craft-agent source list
• craft-agent source get <slug>
• craft-agent source create (см. флаги ниже)
• craft-agent source update <slug> --json '{...}'
• craft-agent source delete <slug>
• craft-agent source validate <slug>
• craft-agent source test <slug>
• craft-agent source init-guide <slug> [--template generic|mcp|api|local]
• craft-agent source init-permissions <slug> [--mode read-only]
• craft-agent source auth-help <slug>

Флаги для source create

Примеры

craft-agent source list
craft-agent source get linear
# MCP-источник с простыми флагами
craft-agent source create --name "Linear" --provider "linear" --type mcp --url "https://mcp.linear.app/sse" --auth-type oauth
# MCP-источник с --json для вложенной конфигурации
craft-agent source create --name "Linear" --provider "linear" --type mcp --json '{"mcp":{"transport":"http","url":"https://mcp.linear.app/sse","authType":"oauth"}}'
# API-источник
craft-agent source create --name "Exa" --provider "exa" --type api --base-url "https://api.exa.ai/" --auth-type header
# Локальный источник
craft-agent source create --name "Docs Folder" --provider "filesystem" --type local --path "~/Documents"
craft-agent source update linear --json '{"enabled":false}'
craft-agent source validate linear
craft-agent source test linear
craft-agent source init-guide linear --template mcp
craft-agent source init-permissions linear --mode read-only
craft-agent source auth-help linear

Примечания

• Используйте простые флаги для базовых значений или --json для вложенных полей конфигурации, специфичных для типа (mcp, api, local).
• init-guide создает базовый файл guide.md на основе типа источника.
• init-permissions создает шаблоны файла permissions.json с правами только для чтения для режима Изучение.
• auth-help возвращает рекомендуемый инструмент аутентификации и режим для использования внутри сессии.
• test — это легковесная проверка через CLI; для полной проверки аутентификации/подключения внутри сессии используйте инструмент MCP source_test.

Скилл

Управление скиллами workspace, хранящимися в файлах skills/{slug}/SKILL.md.

Команды

• craft-agent skill list [--workspace-only] [--project-root <path>]
• craft-agent skill get <slug> [--project-root <path>]
• craft-agent skill where <slug> [--project-root <path>]
• craft-agent skill create (см. флаги ниже)
• craft-agent skill update <slug> --json '{...}' [--project-root <path>]
• craft-agent skill delete <slug>
• craft-agent skill validate <slug> [--source workspace|project|global] [--project-root <path>]

Флаги для skill create

Примеры

craft-agent skill list
craft-agent skill list --workspace-only
craft-agent skill where commit-helper
craft-agent skill create --name "Commit Helper" --description "Generate conventional commits" --slug commit-helper
craft-agent skill create --name "Code Review" --description "Review PRs" --globs "*.ts,*.tsx" --always-allow "Bash" --required-sources "github"
craft-agent skill update commit-helper --json '{"requiredSources":["github"],"body":"Use concise, imperative commit messages."}'
craft-agent skill validate commit-helper
craft-agent skill validate commit-helper --source global
craft-agent skill delete commit-helper

Примечания

• create / update записывают frontmatter и тело контента в SKILL.md.
• Используйте where, чтобы проверить приоритет разрешения (workspace/project/global).
• --project-root ограничивает область разрешения проектной директорией (по умолчанию используется текущая рабочая директория).

Автоматизация

Управление автоматизациями workspace, хранящимися в файле automations.json.

Команды

• craft-agent automation list
• craft-agent automation get <id>
• craft-agent automation create (см. флаги ниже)
• craft-agent automation update <id> (те же флаги, что и для create, все необязательные)
• craft-agent automation delete <id>
• craft-agent automation enable <id>
• craft-agent automation disable <id>
• craft-agent automation duplicate <id>
• craft-agent automation history [<id>] [--limit <n>]
• craft-agent automation last-executed <id>
• craft-agent automation test <id> [--match "..."]
• craft-agent automation lint
• craft-agent automation validate

Флаги для automation create / update

Примеры

craft-agent automation list
craft-agent automation validate
# Простая автоматизация с запросом, с использованием простых флагов
craft-agent automation create --event UserPromptSubmit --prompt "Summarize this prompt"
# Запланированная автоматизация с использованием простых флагов
craft-agent automation create --event SchedulerTick --cron "0 9 * * 1-5" --timezone "Europe/Budapest" --prompt "Give me a morning briefing" --labels "Scheduled" --permission-mode safe
# Сложная автоматизация с использованием --json
craft-agent automation create --event SchedulerTick --json '{"cron":"0 9 * * 1-5","actions":[{"type":"prompt","prompt":"Daily summary"}]}'
craft-agent automation update abc123 --name "Morning Report" --prompt "Updated prompt"
craft-agent automation update abc123 --enabled false
craft-agent automation enable abc123
craft-agent automation duplicate abc123
craft-agent automation history abc123 --limit 10
craft-agent automation last-executed abc123
craft-agent automation test abc123 --match "UserPromptSubmit"
craft-agent automation lint
craft-agent automation delete abc123

Примечания

• Используйте простые флаги для базовых автоматизаций или --json для сложных сопоставлений с несколькими actions.
• --prompt — это ярлык, который автоматически оборачивает текст в действие prompt. Используйте --json с actions для многошаговых автоматизаций.
• lint выполняет быструю проверку корректности сопоставлений и действий (валидность regex, отсутствие действий, избыточные наборы упоминаний в запросе).
• history и last-executed читают данные из automations-history.jsonl, если файл присутствует.
• validate запускает полную проверку схемы и семантики.

Права доступа

Управление правами доступа для режима Изучение, хранящимися в файле permissions.json (на уровне workspace и для каждого источника).

Команды

• craft-agent permission list
• craft-agent permission get [--source <slug>]
• craft-agent permission set [--source <slug>] --json '{...}'
• craft-agent permission add-mcp-pattern "<pattern>" [--comment "..."] [--source <slug>]
• craft-agent permission add-api-endpoint --method GET|POST|... --path "<regex>" [--comment "..."] [--source <slug>]
• craft-agent permission add-bash-pattern "<pattern>" [--comment "..."] [--source <slug>]
• craft-agent permission add-write-path "<glob>" [--source <slug>]
• craft-agent permission remove <index> --type mcp|api|bash|write-path|blocked [--source <slug>]
• craft-agent permission validate [--source <slug>]
• craft-agent permission reset [--source <slug>]

Область действия

Без --source: работает с файлом permissions.json на уровне workspace (глобальные правила).

С --source <slug>: работает с файлом permissions.json конкретного источника (автоматически ограничивает область).

Примеры

# Вывести список всех файлов прав (workspace + источники)
craft-agent permission list
# Получить права доступа workspace
craft-agent permission get
# Получить права доступа конкретного источника
craft-agent permission get --source linear
# Добавить паттерны MCP только для чтения для источника
craft-agent permission add-mcp-pattern "list" --comment "List operations" --source linear
craft-agent permission add-mcp-pattern "get" --comment "Get operations" --source linear
craft-agent permission add-mcp-pattern "search" --comment "Search operations" --source linear
# Добавить правила для конечных точек API
craft-agent permission add-api-endpoint --method GET --path ".*" --comment "All GET requests" --source stripe
# Добавить паттерны для bash
craft-agent permission add-bash-pattern "^ls\\s" --comment "Allow ls"
# Добавить глобальные паттерны для записи
craft-agent permission add-write-path "/tmp/**"
# Удалить правило по индексу и типу
craft-agent permission remove 1 --type mcp --source linear
# Заменить всю конфигурацию
craft-agent permission set --source github --json '{"allowedMcpPatterns":[{"pattern":"list","comment":"List ops"}]}'
# Проверить все права доступа
craft-agent permission validate
# Проверить права доступа конкретного источника
craft-agent permission validate --source linear
# Удалить файл прав (вернуться к значениям по умолчанию)
craft-agent permission reset --source linear

Примечания

• Паттерны MCP на уровне источника автоматически ограничиваются областью действия во время выполнения (например, list становится mcp__<slug>__.*list).
• remove использует 0-базовый индекс внутри указанного массива типов правил. Используйте get, чтобы увидеть индексы.
• validate запускает проверку схемы и regex. Без --source проверяет workspace и все источники.
• reset удаляет файл прав, возвращая настройки к значениям по умолчанию.

Тема

Управление настройками темы на уровне приложения и workspace.

Команды

• craft-agent theme get
• craft-agent theme validate [--preset <id>]
• craft-agent theme list-presets
• craft-agent theme get-preset <id>
• craft-agent theme set-color-theme <id>
• craft-agent theme set-workspace-color-theme <id|default>
• craft-agent theme set-override --json '{...}'
• craft-agent theme reset-override

Примеры

# Проверить текущее состояние темы
craft-agent theme get

# Проверить файл переопределения приложения
craft-agent theme validate

# Проверить один файл пресета
craft-agent theme validate --preset nord

# Вывести список доступных пресетов
craft-agent theme list-presets

# Проверить конкретный пресет
craft-agent theme get-preset dracula

# Установить пресет по умолчанию для приложения
craft-agent theme set-color-theme nord

# Установить переопределение для workspace
craft-agent theme set-workspace-color-theme dracula

# Снять переопределение workspace (наследовать пресет приложения)
craft-agent theme set-workspace-color-theme default

# Заменить переопределение theme.json на уровне приложения
craft-agent theme set-override --json '{"accent":"oklch(0.62 0.21 293)","dark":{"accent":"oklch(0.68 0.21 293)"}}'

# Удалить файл переопределения на уровне приложения
craft-agent theme reset-override

Примечания

• set-color-theme и set-workspace-color-theme требуют существующий ID пресета (default всегда допустим).
• set-override проверяет структуру theme.json перед записью.
• Переопределение workspace хранится в workspace/config.json в поле defaults.colorTheme.
• Переопределение приложения хранится в ~/.craft-agent/theme.json.

Контракт вывода

Все команды возвращают единый JSON-конверт в stdout.

Успех

{ "ok": true, "data": {}, "warnings": [] }

Ошибка

{
  "ok": false,
  "error": {
    "code": "USAGE_ERROR",
    "message": "...",
    "suggestion": "..."
  },
  "warnings": []
}

Коды выхода:

• 0 успех
• 1 ошибка выполнения/внутренний сбой
• 2 ошибка использования/валидации/ввода