kintone Ops

Build, query, and automate Cybozu kintone apps — Japan's leading no-code business platform with global deployments. Use this skill whenever the user mentions...

Security Scan

The skill's code, instructions, and requested credentials are consistent with a kintone API automation tool and do not request unrelated secrets or external installs.

Purpose & Capability

The skill is designed to interact with Cybozu kintone and only requires Node.js plus a kintone base URL and an API token (primaryEnv). Required binary (node) and the declared primary credential (KINTONE_API_TOKEN) match the stated purpose. The code also supports username/password auth for broader access, which is sensible for cross-app discovery and documented in SKILL.md.

Instruction Scope

SKILL.md and the CLI instruct the agent to find apps, inspect schemas, query/update records, and only read/upload files when explicitly asked. That's in-scope. The docs also include sample OpenClaw config edits (~/.openclaw/openclaw.json) and describe running an integration test suite that creates apps/records — the tests are destructive by design and should only be run intentionally. Overall instructions do not direct reading of unrelated local secrets, but you should avoid running integration tests or importing files unless you intend to modify the target kintone environment.

Install Mechanism

There is no install spec — the skill is delivered as a Node script and docs. No external downloads, third-party package installs, or archive extraction are used in the skill bundle, which minimizes installation risk. It requires Node 18+ to be present on PATH.

Credentials

Primary credential KINTONE_API_TOKEN is appropriate and proportional for per-app operations. The skill also supports KINTONE_USERNAME and KINTONE_PASSWORD (documented and present in the script) for broader account-level access; those optional credentials are more powerful and carry greater risk. The registry metadata lists KINTONE_BASE_URL and primaryEnv KINTONE_API_TOKEN, but does not explicitly list the optional username/password env vars — this is a minor inconsistency to be aware of (they are supported, just optional).

Persistence & Privilege

The skill does not request always:true and is user-invocable only; it does suggest storing credentials in your OpenClaw config (~/.openclaw/openclaw.json) which is normal for convenience but requires you to trust the stored secret location. The skill does not modify other skills or system-wide settings.

Assessment

This skill appears to do exactly what it claims: a Node-based CLI to call kintone REST APIs. Before installing, confirm you will only provide the minimal credentials needed: prefer per-app KINTONE_API_TOKEN(s) rather than KINTONE_USERNAME/KINTONE_PASSWORD unless you truly need broad account access. Do not run the integration tests unless you expect the script to create/delete apps/records in your kintone environment. If you plan to store credentials in ~/.openclaw/openclaw.json, ensure that file is protected and you trust the machine. Finally, review the included scripts (scripts/kintone-api.mjs) yourself if you have any concerns — the code enforces HTTPS and restricts hostnames to official kintone domains, and it does not call any third-party endpoints.

kintone

Programmatic access to the Cybozu kintone platform — query records, manage apps, automate workflows, and handle bulk data operations.

Prerequisites

• Node.js 18+ (for native fetch support)
• A kintone domain such as mycompany.cybozu.com, mycompany.cybozu.cn, or mycompany.kintone.com
• An API token or username/password credentials

Environment Setup

This skill needs KINTONE_BASE_URL plus one authentication method:

• Preferred: KINTONE_API_TOKEN
• Alternative: KINTONE_USERNAME + KINTONE_PASSWORD

Authentication strategy

Choose the authentication method based on the user's scope:

• Use KINTONE_API_TOKEN when the user is working with one specific app, or a known set of apps that already have API tokens.
• KINTONE_API_TOKEN may contain multiple app tokens as a comma-separated string such as token-app-a,token-app-b. This script passes that value directly to the X-Cybozu-API-Token header, so multi-app token auth is supported as long as kintone accepts those tokens for the target app.
• Use KINTONE_USERNAME + KINTONE_PASSWORD when the user wants to search, inspect, or operate across any apps that the account can access.
• Explain the tradeoff clearly: password auth usually reaches more apps, but it also grants the full permissions of that user account and therefore carries higher risk.
• If the user only needs to operate on a specified app or a small fixed set of apps, prefer API tokens.

Supported domains

This skill supports the standard kintone hosted domains:

• https://<subdomain>.cybozu.com
• https://<subdomain>.cybozu.cn
• https://<subdomain>.kintone.com

The script uses the supplied KINTONE_BASE_URL and appends the normal REST API path prefixes:

• Standard apps: /k/v1/...
• Guest spaces: /k/guest/{spaceId}/v1/...

Security notes

• Only use KINTONE_BASE_URL values that point to an official kintone hosted domain ending in .cybozu.com, .cybozu.cn, or .kintone.com.
• Treat authentication as proportional to scope: use KINTONE_API_TOKEN for specific apps whenever possible, and use KINTONE_USERNAME + KINTONE_PASSWORD only when the user truly needs broader app discovery or cross-app access.
• Never send kintone credentials or record data to third-party domains. This skill is intended to talk only to the configured kintone site.
• Only read or upload files when the user explicitly asks for records import or files upload and gives a concrete file path.

OpenClaw / ClawHub configuration

If you install this skill through OpenClaw or ClawHub, configure it in ~/.openclaw/openclaw.json:

{
  skills: {
    entries: {
      kintone: {
        enabled: true,
        env: {
          KINTONE_BASE_URL: "https://mycompany.kintone.com",
          KINTONE_API_TOKEN: "your-api-token-here",
        },
      },
    },
  },
}

If you prefer password authentication instead of an API token:

{
  skills: {
    entries: {
      kintone: {
        enabled: true,
        env: {
          KINTONE_BASE_URL: "https://mycompany.kintone.com",
          KINTONE_USERNAME: "[e-mail]",
          KINTONE_PASSWORD: "your-password",
        },
      },
    },
  },
}

primaryEnv is set to KINTONE_API_TOKEN, so OpenClaw can treat token auth as the default secret for this skill. Use the env block when you need username/password instead.

Shell environment setup

If you are running the bundled CLI manually outside OpenClaw, export these variables in your shell:

# Required base URL
export KINTONE_BASE_URL="https://mycompany.kintone.com"

# Preferred authentication
export KINTONE_API_TOKEN="your-api-token-here"

# Alternative: password auth (grants broader access)
export KINTONE_USERNAME="[e-mail]"
export KINTONE_PASSWORD="your-password"

API tokens are scoped per-app and recommended for production use. Generate them in each app's Settings -> API Token. For multi-app access, comma-separate tokens: KINTONE_API_TOKEN="token1,token2".

---

🤖 AI Assistant Guidelines (How to Handle User Requests)

Language handling

• Understand and handle user requests in Japanese, English, and Chinese.
• Reply in the user's language unless they ask you to switch languages.
• Keep kintone field codes, option values, and app names exactly as they exist in the target environment. Do not translate actual field codes or workflow action names unless the user explicitly asks for explanation.
• Recognize that different regions may use different domain suffixes, UI languages, field labels, and app names. Do not assume Japanese-only deployments.
• Never read unrelated local secrets or arbitrary files. Only use files the user explicitly names for import or upload tasks.

Users will rarely provide App IDs or exact field names (e.g., "Add a leave request for tomorrow"). When handling natural language requests, you MUST follow this interaction pattern:

1. Find the App: If the App ID isn't provided, use apps list or apps list --name "Keyword" to find the most likely app based on the user's intent. Do not guess App IDs.
2. Inspect the Schema: ALWAYS run apps fields --app <ID> to understand the app's structure, identify required fields, and see the exact field codes and types.
3. Map the Data: Map the user's natural language input (e.g., "tomorrow") to the strict field formats required by kintone (e.g., 2026-03-12 for DATE fields).
4. Ask for Missing Info: If the schema has required: true fields that the user didn't provide, stop and ask the user for that specific information.
5. Execute and Verify: Execute the command (e.g., records create). If an error occurs (e.g., validation error CB_VA01), read the error, adjust your payload, and retry. Tell the user when successful.

---

Bundled Script Usage

All operations use the bundled script at scripts/kintone-api.mjs. Run it with:

node <skill-path>/scripts/kintone-api.mjs <command> <sub-command> [options]

Add --json to any command for machine-readable JSON output. Add --guest-space-id <ID> for guest space operations.

---

Records

Query Records

# List all records from app 1
node <skill>/scripts/kintone-api.mjs records get --app 1

# With kintone query filter
node <skill>/scripts/kintone-api.mjs records get --app 1 \
  --query 'ステータス = "商談中" and 売上見込 > 1000000 order by 最終連絡 desc'

# Limit results
node <skill>/scripts/kintone-api.mjs records get --app 1 --limit 10

# Select specific fields
node <skill>/scripts/kintone-api.mjs records get --app 1 --fields "会社名,担当者,ステータス"

# JSON output for parsing
node <skill>/scripts/kintone-api.mjs records get --app 1 --json

Auto-paginates automatically (kintone returns max 500 records per request).

Get Single Record

node <skill>/scripts/kintone-api.mjs records get-one --app 1 --id 42

Create Record

node <skill>/scripts/kintone-api.mjs records create --app 1 \
  --data '{"会社名": "New Corp", "担当者": "石原", "ステータス": "初回接触"}'

Values are automatically wrapped in kintone's {"value": ...} format.

Update Record

node <skill>/scripts/kintone-api.mjs records update --app 1 --id 42 \
  --data '{"ステータス": "受注", "売上見込": 5800000}'

# With optimistic locking
node <skill>/scripts/kintone-api.mjs records update --app 1 --id 42 \
  --data '{"ステータス": "受注"}' --revision 14

Delete Records

node <skill>/scripts/kintone-api.mjs records delete --app 1 --ids "100,101,102"

Bulk Update

Update all records matching a query:

# Preview (no --yes flag)
node <skill>/scripts/kintone-api.mjs records bulk-update --app 1 \
  --query 'ステータス = "初回接触" and 最終連絡 < "2025-12-01"' \
  --set '{"ステータス": "休眠"}'

# Execute
node <skill>/scripts/kintone-api.mjs records bulk-update --app 1 \
  --query 'ステータス = "初回接触" and 最終連絡 < "2025-12-01"' \
  --set '{"ステータス": "休眠"}' --yes

Automatically chunks into 100-record batches.

---

Export / Import

Export to CSV

# Export to file (UTF-8 with BOM for Excel compatibility)
node <skill>/scripts/kintone-api.mjs records export --app 1 --output ./export.csv

# Export with filter
node <skill>/scripts/kintone-api.mjs records export --app 1 \
  --query 'ステータス != "休眠"' --output ./active_customers.csv

# Export as JSON
node <skill>/scripts/kintone-api.mjs records export --app 1 --json

Uses the Cursor API for efficient large dataset exports.

Import from CSV

node <skill>/scripts/kintone-api.mjs records import --app 1 --file ./data.csv

CSV must have a header row with field codes matching the app schema.

---

Apps

List Apps

node <skill>/scripts/kintone-api.mjs apps list
node <skill>/scripts/kintone-api.mjs apps list --name "顧客"

Get App Details

node <skill>/scripts/kintone-api.mjs apps get --app 1

View Field Schema

node <skill>/scripts/kintone-api.mjs apps fields --app 1
# Preview (uncommitted changes)
node <skill>/scripts/kintone-api.mjs apps fields --app 1 --preview

Always inspect fields before creating or updating records to understand the schema, required fields, and correct field codes. Never guess field codes.

View Form Layout

node <skill>/scripts/kintone-api.mjs apps layout --app 1

View Custom Views

node <skill>/scripts/kintone-api.mjs apps views --app 1

Create App

node <skill>/scripts/kintone-api.mjs apps create --name "新しいアプリ"
node <skill>/scripts/kintone-api.mjs apps create --name "チームアプリ" --space 5

Creates in preview mode. Use apps deploy to deploy to production.

Deploy / Check Deploy Status

node <skill>/scripts/kintone-api.mjs apps deploy --app 1
node <skill>/scripts/kintone-api.mjs apps deploy-status --app 1

---

Workflow (Process Management)

Update Record Status

node <skill>/scripts/kintone-api.mjs workflow status --app 5 --id 301 --action "承認"

Bulk Status Update

node <skill>/scripts/kintone-api.mjs workflow bulk-status --app 5 \
  --data '[{"id": 301, "action": "承認"}, {"id": 302, "action": "承認"}]'

Update Assignees

node <skill>/scripts/kintone-api.mjs workflow assignee --app 5 --id 301 \
  --assignees "user1,user2"

---

Comments

# Get comments
node <skill>/scripts/kintone-api.mjs comments get --app 1 --id 42

# Add comment (with optional @mentions)
node <skill>/scripts/kintone-api.mjs comments add --app 1 --id 42 \
  --text "確認しました" --mention "tanaka,sato"

# Delete comment
node <skill>/scripts/kintone-api.mjs comments delete --app 1 --id 42 --comment-id 5

---

Files

Upload

node <skill>/scripts/kintone-api.mjs files upload --file ./document.pdf
# Returns fileKey — use it to attach to a record's FILE field

Download

node <skill>/scripts/kintone-api.mjs files download \
  --file-key "20260301xxxx" --output ./downloaded.pdf

Workflow for attaching a file to a record:

1. Upload the file → get fileKey
2. Update the record's FILE field: --data '{"添付ファイル": [{"fileKey": "xxx"}]}'

---

Spaces

# Get space details
node <skill>/scripts/kintone-api.mjs space get --id 1

# Get space members
node <skill>/scripts/kintone-api.mjs space members --id 1

---

Generic API Call

For any API endpoint not covered by specific commands, use the generic api command:

# GET request
node <skill>/scripts/kintone-api.mjs api \
  --method GET --path "app/settings.json" --data '{"app": 1}'

# PUT request (update app settings)
node <skill>/scripts/kintone-api.mjs api \
  --method PUT --path "preview/app/settings.json" \
  --data '{"app": 1, "name": "New Name"}'

# Manage permissions
node <skill>/scripts/kintone-api.mjs api \
  --method GET --path "app/acl.json" --data '{"app": 1}'

# Notification settings
node <skill>/scripts/kintone-api.mjs api \
  --method GET --path "app/notifications/general.json" --data '{"app": 1}'

# Plugin management
node <skill>/scripts/kintone-api.mjs api \
  --method GET --path "plugins.json"

This provides full coverage of all kintone REST API endpoints. Refer to references/api-endpoints.md for the complete endpoint list with parameters.

---

kintone Query Syntax

kintone uses its own query language. Key syntax:

field_code operator "value" [and|or] field_code operator "value" [order by field_code asc|desc] [limit N] [offset N]

Operators: =, !=, >, <, >=, <=, in, not in, like, not like

Examples:

ステータス = "商談中"
会社名 like "Tech" and 売上見込 > 1000000
ステータス in ("商談中", "提案済") and 担当者 in (LOGINUSER())
作成日時 > "2026-01-01T00:00:00Z"
order by 更新日時 desc limit 100

Functions: LOGINUSER(), PRIMARY_ORGANIZATION(), NOW(), TODAY(), THIS_MONTH(), LAST_MONTH(), THIS_YEAR()

Refer to references/query-syntax.md for the complete syntax guide.

---

Field Types

kintone has specific value formats per field type:

Type	Value Format	Example
SINGLE_LINE_TEXT	string	"Hello"
MULTI_LINE_TEXT	string	"Line1\nLine2"
NUMBER	string (numeric)	"12345"
DATE	YYYY-MM-DD	"2026-03-01"
TIME	HH:MM	"14:30"
DATETIME	ISO 8601 UTC	"2026-03-01T05:30:00Z"
DROP_DOWN	string	"Option A"
CHECK_BOX	array	["A", "B"]
MULTI_SELECT	array	["X", "Y"]
USER_SELECT	array of objects	[{"code": "user1"}]
FILE	array of objects	[{"fileKey": "xxx"}]
SUBTABLE	array of row objects	see below

Subtable format:

[{"value": {"品名": {"value": "Widget"}, "数量": {"value": "10"}}}]

Refer to references/field-types.md for the complete type reference.

---

Error Handling

Code	Meaning	Solution
520 CB_ILLEGAL_TOKEN	Invalid API token	Regenerate token in app settings; verify permissions
409 CB_CONFLICT	Revision mismatch	Fetch latest record, check changes, retry with current revision
400 CB_VA01	Validation error	Check field types with apps fields; ensure required fields are set
403 CB_NO02	No permission	Check app/record permissions; API tokens are per-app
414 Request-URI Too Long	Query too long	Break large in() clauses into multiple queries
500 CB_IJ01	Server error	Retry after 30s; check Cybozu status page

---

Best Practices

1. Always inspect schema first — Run apps fields --app <ID> before creating or updating records.
2. Use --json for parsing — When processing results programmatically, always use --json output.
3. Preview before bulk — Run bulk-update without --yes first to see the preview count.
4. Respect rate limits — kintone limits concurrent connections (typically 10 per domain).
5. Use revision for updates — Include --revision on critical updates to prevent overwrite conflicts.
6. API tokens per app — Each token only grants access to its specific app. Use comma-separated tokens for multi-app.