kuroco-admin-api

Kuroco Admin API Skill

Overview

A skill for operating the Kuroco management API (admin_api) kuroco-admin from the CLI.

admin_api's 5 modes:

whoami: Retrieve session information — returns member_id, name, group_ids
discover: Explore available modules and controllers
schema: Retrieve request/response schemas for controllers/services
advise: Tell it what you want to do in natural language, and the AI will answer with the API to call and the procedure
execute: Execute an API (GET/POST) — --columnsResponse columns can be selected with

Authentication method: kuroco-admin login with session cookie ~/.kuroco-admin/cookies.txt . Subsequent commands automatically send the Cookie.

Prerequisites:

Bun runtime is installed
kuroco-admin The CLI is built or added to PATH
kuroco-admin login --url <管理画面URL> Logged in with
All operations are executed with the permissions of the logged-in user

Minimum operation flow (reads: 2-3 tool calls, writes: 3-4 tool calls):

Bash: Authentication check (kuroco-admin whoami --json）

Bash: Grasp the API structure (kuroco-admin discover --json or kuroco-admin advise "やりたいこと" --json) — can be omitted if mt/ct are already determined from examples in this skill, etc.

(when writing) Bash: Retrieve schema (kuroco-admin help topics/topics_edit --json. If ext_col is needed, use the Step 3 の exec --param action=schema format)

Bash: Execute API (kuroco-admin exec ...）

advise is the most efficient. Just tell it what you want to do in natural language, and the AI will answer with the API to call, the procedure, and the parameters. If mt/ct are unknown, use advise first.

Setup

Install

# CLI ソースディレクトリ
cd /path/to/admin_cli

# ビルド（スタンドアロンバイナリ）
bun build --compile kuroco-admin.ts --outfile kuroco-admin

# PATHに追加（任意）
cp kuroco-admin /usr/local/bin/

Login

kuroco-admin login --url https://example.g.kuroco-mng.app
# → メールアドレスとパスワードを対話的に入力
# → ~/.kuroco-admin/config.json と cookies.txt が保存される

Operation flow

All API operations must follow this flow.

Step 1: Authentication check

kuroco-admin whoami --json

Success (exit 0) → {"success":true,"data":{"member_id":...}} is returned → go to Step 2
Failure (exit 2) → session expired.kuroco-admin login --url <URL> Log in again with

Step 2: Grasp the API structure

Omission condition: If the target mt/ct is already determined from examples in this skill or past execution results, this step may be omitted (do not repeat unnecessary discover/advise).

Use the three methods appropriately according to the purpose:

Method A: advise (AI-assisted, recommended)

Tell it what you want to do in natural language, and the AI will answer with the API to call and the procedure:

kuroco-admin advise "記事を新しく作成したい" --json

Response steps includes mt/ct/http_method/mode/endpoint.endpoint と api_spec is automatically generated by the system (no hallucination).summary, description, body_example is AI-generated.

Method B: discover (module/controller list)

# 全モジュール一覧
kuroco-admin discover --json

# 特定モジュールのコントローラ一覧
kuroco-admin discover --mt topics --json

Method C: help (schema retrieval)

Request/response schema for a specific controller:

kuroco-admin help topics/topics_edit --json

How to use them separately:

Method Purpose

advise(Recommended) AI suggests API procedures based on what you want to do (when mt/ct is unknown)

discover Programmatically enumerate modules/controllers

help Check the field definitions, types, and required items of a specific controller

Method	Purpose
advise(Recommended)	AI suggests API procedures based on what you want to do (when mt/ct is unknown)
discover	Programmatically enumerate modules/controllers
help	Check the field definitions, types, and required items of a specific controller

Step 3: Schema retrieval (required for write operations)

For write operations (INSERT/UPDATE), always retrieve the schema and check the field structure:

kuroco-admin help topics/topics_edit --json

The response is in JSON Schema format.data.request.properties contains the field definitions, anddata.request.required contains the required fields.

When a schema including ext_col is needed:

help In the command, topics_group_id cannot be specified, so retrieve it directly withexec :

kuroco-admin exec --mt topics --ct topics_edit --param action=schema --param topics_group_id=99 --json

Note:

topics_group_id If omitted, only generic fields are included (ext_col is not included)

topics_group_id If specified, the field names of block editor and extended items (ext_1, ext_14 etc.), types, and required flags can be retrieved

list-type controllers (topics_listetc.) return an empty schema, so specify a controller for writing (topics_edit)

The ct for schema retrieval and the ct for execution may differ. For Topics, it is confirmed as "schema retrieval =topics_edit, INSERT/UPDATE/DELETE execution =topics_edit_api". Check the ct for execution of other modules in the discover / advise results

Response x-kuroco-type lets you determine the field type (wysiwyg, json, checkbox, file etc.)

Step 4: API execution

Once authentication verification and structure understanding are complete, execute the API according to theAPI execution patterns.

Step 5: Handling authentication failure / session expiration

If exit code 2 (AUTH_ERROR / SESSION_EXPIRED / LOGIN_REQUIRED) is returned:

Tell the user that re-login is required
kuroco-admin login --url <URL> Execute
Perform the operation again after logging in

If an authentication error occurs during a multi-step operation:

Stop the operation immediately
Report to the user how far the operation succeeded
Guide the user to re-login
After re-authentication, resume from the incomplete operation

API execution patterns

Parameter format

kuroco-admin exec In module/controller shorthand format, or individual specification with --mt/--ct can be used.

Parameters	Description	Example
`mt`	Module name (lowercase)	`topics`, `member`, `inquiry`
`ct`	Controller name	`topics_list`, `topics_edit`, `member_list`

# ショートハンド形式（推奨）
kuroco-admin exec topics/topics_list --json

# 個別指定
kuroco-admin exec --mt topics --ct topics_list --json

Note: model/method Do not use the mt/ct format. HTML may be returned. Always use the

GET request (list retrieval / search)

# 基本的な一覧取得（columns + cnt で最小限のレスポンス）
kuroco-admin exec topics/topics_list \
  --param "topics_group_id[]=1" \
  --param cnt=10 \
  --columns topics_id,subject,ymd \
  --json

# 検索・フィルタリング
kuroco-admin exec topics/topics_list \
  --param "topics_group_id[]=1" \
  --param "keyword=検索語" \
  --param cnt=20 \
  --columns topics_id,subject \
  --json

# ページネーション
kuroco-admin exec topics/topics_list \
  --param "topics_group_id[]=1" \
  --param pageID=2 \
  --param cnt=20 \
  --json

columns principle: For list retrieval / search-type GET requests, always specify --columns (action=schema Metadata retrieval such as etc. is out of scope). On supported endpoints, server-side filtering is applied; even on unsupported ones it is simply ignored, so it can always be specified without issue.

keyword behavior: By default, partial-match search targeting title (subject), body, category, and extended fields. Space-separated terms are AND search; alphanumeric characters are case-insensitive. Target columns can be narrowed down with target_col_for_keyword (details: kuroco-docs reference/keyword-search-types.md）。

Parameter behavior check: If the exact behavior of a parameter is not described in this skill other than the above, check the definition with kuroco-admin help <mt>/<ct> --json .

Quoting convention: For[]containing values that may be interpreted by the shell ( --param は "key=value" such as spaces or multibyte values like Japanese), enclose the entire value in double quotes.

POST requests (create, update, delete)

# 新規作成（INSERT）
kuroco-admin exec topics/topics_edit_api \
  --MODE INSERT \
  --data '{"subject":"タイトル","contents":"本文","topics_group_id":1}' \
  --json

# 更新（UPDATE）
kuroco-admin exec topics/topics_edit_api \
  --MODE UPDATE \
  --data '{"topics_id":123,"subject":"更新後タイトル"}' \
  --json

# 削除（DELETE）
kuroco-admin exec topics/topics_edit_api \
  --MODE DELETE \
  --data '{"topics_id":123}' \
  --json

dry-run (preview)

Check request contents before execution:

kuroco-admin exec topics/topics_edit_api \
  --MODE INSERT \
  --data '{"subject":"テスト"}' \
  --dry-run

Service invocation

Automatically distinguish controller (starts with lowercase) and service (starts with uppercase):

# コントローラ: 小文字開始
kuroco-admin exec topics/topics_list --json

# サービス: 大文字開始（PHP側で自動検出）
kuroco-admin exec Email/send --data '{"to":"user@example.com","subject":"件名"}' --json

Important rules

Rule	Description
--json flag	When called from an AI agent, always specify `--json` (exception: `--dry-run` is preview output, so `--json` not required)
GET array parameters	`--param "topics_group_id[]=1"` As in `[]` , the
suffix is required	`--data` POST array parameters `{"topics_group_id": [1]}`）
Native JSON array within (e.g.:	Count limit `--param cnt=N` If the response is large, limit with
columns specification	`--columns col1,col2` Minimize response columns with
Confirmation of change operations	INSERT/UPDATE/DELETEはConfirm with the user before executionto do
Resolution of undetermined values	For fields included in the scope of the request but whose values cannot be determined from the request content, regardless of whether they are required, do not fill them in by guessing or with defaults; present the field name, type, and candidate values and confirm with the user
Use dry-run	Before write operations, check the request contents with `--dry-run` to check the request content

For details, refer to references/cli-commands.md refer to

Response structure

Success response (--json)

{
  "success": true,
  "data": { ... },
  "errors": []
}

Error response (--json)

{
  "success": false,
  "data": null,
  "errors": [{ "code": "API_ERROR", "message": "..." }]
}

Keys of list responses

The keys of the list array in the response correspond to ct :

ct	Response list keys
`topics_list`	`data.topics_list`
`topics_group_list`	`data.topics_group_list`
`member_list`	`data.member_list`

Pagination

{
  "pageInfo": {
    "totalCnt": 150,
    "perPage": 20,
    "totalPageCnt": 8,
    "pageNo": 1
  }
}

Error handling

Exit Codes

Code	Meaning	Action
0	Success	—
1	General errors (INVALID_PARAM, NETWORK_ERROR, API_ERROR)	Check the error message, fix the parameters
2	Authentication errors (AUTH_ERROR, SESSION_EXPIRED, LOGIN_REQUIRED)	`kuroco-admin login` log in again with

For details, refer to references/error-handling.md refer to

Module relationship map

Main parent-child relationships. The parent ID is required for child operations:

TopicsGroup → Topics         (topics_group_id 必須)
MemberGroup → Member         (group_id 必須)
InquiryForm → InquiryMessage (inquiry_id 必須)
TagCategory → Tag            (tag_category_id 必須)

Before operating, check the groups available in the parent list:

kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json

For details, refer to references/api-discovery.md refer to

Security notes

Do not display or log Cookie values — ~/.kuroco-admin/cookies.txt is protected with mode 0o600
--verbose Do not show the output of — Cookie values are included in HTTP headers
Always perform modification operations after user confirmation — INSERT/UPDATE/DELETE are difficult to undo
--dry-run make use of — preview the request content before writing
Saving API response files requires user consent — may contain personal information

Anti-patterns

Common mistake	Problem	Recommended
`--json` Execute without adding	Hard to parse in human-oriented format	In AI agent, always `--json`
`--columns` GET without specifying	The response is huge	Always specify `--columns` specify
Do not check the exit code	Not noticing authentication expiration	If exit code 2, log in again
Write without schema	Missing required fields	`help` Execute after checking the schema with
`--verbose` Keep the output in logs	Cookie values leak	Use only when debugging, do not share the output
`model/method` Specify the API in format	HTML may be returned	Always `mt/ct` use the format

Parallel execution

Independent API calls can be executed in parallel by issuing multiple Bash tool calls simultaneously:

# 別々のBash tool callで同時発行
kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json
kuroco-admin exec member/member_group_list --columns group_id,group_nm --json

Cooperation with other skills

Skill	Purpose	How to use them differently
`/kuroco-admin-mcp`	Connection to and tool use of Admin MCP (management MCP server)	Recommended means of management operations from AI agents. Connect from MCP clients (Claude Desktop / claude.ai / Claude Code, etc.)
`/kuroco-api-content`	Frontend API design and authentication patterns, content CRUD patterns	End-user-facing API
`/kuroco-frontend-integration`	Nuxt.js/Next.js integration, AI automatic deployment	Frontend implementation
`/kuroco-docs`	Refer to Kuroco documentation	Official documentation search

This skill specializes in executing admin_api via CLI. Admin MCP (/kuroco-admin-mcp) is recommended for administrative operations from AI agents. This skill is an alternative for environments where MCP connections cannot be configured or for embedding into Bash scripts. For frontend API (*.g.kuroco.app) operations, use the related skills above.