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

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

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

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

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

Режимы ввода

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

Лейбл

Управление лейблами 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-add <id> --semantic "<yes/no question>" [--threshold 0.9] [--value "..."] [--description "..."] (семантическое правило; требуется включённая модель принятия решений в Настройки > AI)
• 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 для вложенных или пакетных обновлений.
• Идентификаторы — стабильные slug, генерируемые из name при создании.
• Используйте --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, чтобы посмотреть приоритет разрешения project/workspace/global.
• --project-root ограничивает разрешение каталогом проекта (по умолчанию — cwd).

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

Управление автоматизациями 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

Поля без отдельных флагов — conditions, semanticCondition (да/нет-гейт модели принятия решений) и telegramTopic — передаются в --json; вся конфигурация валидируется перед записью.

Примеры

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 для сложных matcher с несколькими actions.
• --prompt — сокращение, которое автоматически оборачивает текст в действие prompt. Для автоматизаций с несколькими действиями используйте --json с actions.
• lint выполняет быструю проверку корректности matcher/action (валидность regex, отсутствующие actions, слишком большие наборы упоминаний запроса).
• 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 этого источника (автоматически ограничен).

Примеры

# Список всех файлов permissions (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 endpoint
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"
# Добавить glob для путей записи
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
# Удалить файл permissions (вернуться к значениям по умолчанию)
craft-agent permission reset --source linear

Примечания

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

Тема

Управление настройками темы на уровне приложения и 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 — ошибка использования/валидации/ввода