kintone-agent

name	kintone-agent
description	Build, query, and automate Cybozu kintone apps — Japan's leading no-code business platform
author	hanabi-jpn
version	1.0.0
tags	["kintone","cybozu","no-code","business-apps","japan","database","workflow","automation"]

╔═══════════════════════════════════════════════════╗
║  ┌───────────────────────────────────────────┐    ║
║  │  K I N T O N E   A G E N T               │    ║
║  │     ━━━━━━━━━━━━━━━━━━━━━━                │    ║
║  │  🔧 Apps → Records → Workflow → Bulk     │    ║
║  │     Cybozu No-Code Platform CLI           │    ║
║  └───────────────────────────────────────────┘    ║
╚═══════════════════════════════════════════════════╝

kintone cybozu no-code business-apps workflow-engine

Turn kintone into a programmable powerhouse -- query records, build apps, and automate workflows from the command line at the speed of thought.

---

Overview

kintone Agent bridges the gap between Cybozu kintone's intuitive no-code interface and the power-user demands of developers, system integrators, and IT administrators who need programmatic control over their business applications. kintone is the dominant no-code/low-code platform in Japan, deployed across enterprises of every scale -- from three-person startups tracking inventory to multinational corporations running complex approval workflows across dozens of departments. This skill gives you direct, scriptable access to the full kintone REST API, enabling operations that would take hundreds of clicks through the GUI to be executed in a single command.

The agent supports the complete spectrum of kintone operations: creating and modifying apps and their field schemas, performing CRUD on records with complex query syntax, managing custom views and layouts, triggering and monitoring process management (workflow) transitions, handling file attachments, administering users and spaces, and even scaffolding plugin development. Bulk operations are first-class citizens -- import thousands of records from CSV, export filtered datasets for analysis, or update fields across millions of records using kintone's native bulk API endpoints. The agent understands kintone's unique query language and translates natural expressions into valid queries, making ad-hoc data exploration seamless.

Architecture:

  ┌──────────────────────────────────────────────────────────┐
  │                    kintone Agent CLI                      │
  │                                                          │
  │  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐  │
  │  │  Apps   │ │ Records │ │ Workflow │ │    Bulk      │  │
  │  │ Manager │ │  Engine │ │  Engine  │ │  Processor   │  │
  │  └────┬────┘ └────┬────┘ └────┬─────┘ └──────┬───────┘  │
  │       │           │           │               │          │
  │  ┌────▼───────────▼───────────▼───────────────▼────────┐ │
  │  │            Query Builder & Validator                 │ │
  │  │    (kintone query syntax ↔ natural language)         │ │
  │  └──────────────────────┬──────────────────────────────┘ │
  │                         │                                │
  │  ┌──────────────────────▼──────────────────────────────┐ │
  │  │       Auth Layer (API Token / Password / OAuth)      │ │
  │  └──────────────────────┬──────────────────────────────┘ │
  └─────────────────────────┼────────────────────────────────┘
                            │ HTTPS
                            ▼
               ┌─────────────────────────┐
               │   {subdomain}.cybozu.com │
               │     kintone REST API     │
               └─────────────────────────┘

---

System Prompt Instructions

You are the kintone Agent, a specialist in Cybozu kintone platform automation. Follow these rules precisely:

1. Authenticate using API tokens (X-Cybozu-API-Token header) by default. Support password authentication (X-Cybozu-Authorization, Base64-encoded) and OAuth as alternatives.
2. All API requests target https://{KINTONE_DOMAIN}/k/v1/. Validate the domain format before making requests; it must end with .cybozu.com or .kintone.com.
3. Construct kintone query strings using proper syntax: field codes in backtick-like notation, operators (=, !=, >, <, >=, <=, in, not in, like, not like), and combinators (and, or). Always validate query syntax before execution.
4. Handle kintone's unique field types correctly: SINGLE_LINE_TEXT, MULTI_LINE_TEXT, NUMBER, CALC, RICH_TEXT, CHECK_BOX, RADIO_BUTTON, DROP_DOWN, MULTI_SELECT, DATE, TIME, DATETIME, FILE, LINK, USER_SELECT, ORGANIZATION_SELECT, GROUP_SELECT, SUBTABLE, RECORD_NUMBER, CREATOR, MODIFIER, CREATED_TIME, UPDATED_TIME, STATUS, STATUS_ASSIGNEE, CATEGORY.
5. For record creation and updates, validate field values against their field type. Reject invalid data before making API calls (e.g., non-numeric values for NUMBER fields).
6. Bulk operations must use the /records.json endpoint with arrays. Maximum 100 records per POST/PUT request, 500 record IDs per DELETE request. Chunk automatically for larger datasets.
7. When exporting data, default to CSV format. Support JSON, TSV, and Excel formats. Include header row with field labels (not field codes) by default.
8. App deployment requires two steps: first update the preview (/preview/app.json), then deploy (/preview/app/deploy.json). Always confirm deployment status before reporting success.
9. File operations use the /file.json endpoint. Upload returns a fileKey that must be used within the same transaction to attach to a record.
10. Process management (workflow) operations must respect the current status. Only valid transitions from the current status are permitted. Use /record/status.json for transitions.
11. Space and thread operations target /space.json and /space/thread.json. Guest spaces have separate endpoints under /guest/{spaceId}/.
12. When creating or modifying apps, always preview changes first and require explicit confirmation before deploying to production.
13. Respect kintone's field code naming convention: alphanumeric characters and underscores only, starting with a letter. Auto-generate valid codes from Japanese field labels using romanization.
14. Handle kintone's revision system: include revision in updates to prevent concurrent modification conflicts. On conflict (HTTP 409), report the current revision and prompt for resolution.
15. Support lookup fields by resolving related app references. When a field is a lookup, fetch and display the source record's display field.
16. Rate limit awareness: kintone has a concurrent connection limit per domain (typically 10). Queue requests and process with appropriate concurrency.
17. For plugin development scaffolding, generate the manifest.json, config.json, and directory structure per Cybozu's plugin specification.
18. Always display record numbers with the app identifier prefix for clarity (e.g., APP-42 #1234).

---

Environment Variables

Variable	Required	Default	Description
KINTONE_DOMAIN	Yes	-	Your kintone subdomain (e.g., mycompany.cybozu.com)
KINTONE_API_TOKEN	Yes	-	API token generated from app settings (can be comma-separated for multi-app access)
KINTONE_USERNAME	No	-	Login username for password-based authentication (alternative to API token)
KINTONE_PASSWORD	No	-	Login password (used with KINTONE_USERNAME, Base64-encoded in transit)
KINTONE_GUEST_SPACE_ID	No	-	Guest space ID for accessing guest space apps
KINTONE_OUTPUT_FORMAT	No	table	Default output format: table, json, csv
KINTONE_CONCURRENCY	No	5	Maximum concurrent API connections (max 10 per domain)

---

Commands

kt apps

List all accessible kintone apps.

$ kt apps

  App ID  Name                      Creator        Records  Updated
  ──────  ────────────────────────  ─────────────  ───────  ────────────
  1       顧客管理                   石原 達也      12,847   2026-03-01
  5       案件管理                   佐藤 花子      3,291    2026-02-28
  12      日報アプリ                 田中 太郎      45,102   2026-03-01
  18      経費申請                   山田 次郎      8,553    2026-02-27
  24      在庫管理                   鈴木 一郎      1,205    2026-03-01
  31      採用管理                   高橋 美咲      423      2026-02-25

  Total: 6 apps accessible with current token

kt records

Fetch records from an app with optional query filtering.

$ kt records --app 1 --query "会社名 like \"Tech\" and ステータス in (\"商談中\", \"提案済\")" --limit 5

  #      会社名              担当者      ステータス  売上見込     最終連絡
  ─────  ──────────────────  ──────────  ──────────  ──────────  ──────────
  #1042  Tech Solutions      石原 達也   商談中      ¥5,400,000  2026-02-28
  #1089  TechBridge Corp     佐藤 花子   提案済      ¥3,200,000  2026-02-25
  #1134  NextTech Inc.       石原 達也   商談中      ¥8,100,000  2026-03-01
  #1201  TechForward Ltd.    田中 太郎   提案済      ¥1,800,000  2026-02-20
  #1256  GreenTech Japan     山田 次郎   商談中      ¥4,500,000  2026-02-27

  Showing 5 of 23 matching records (App: 顧客管理)

kt create

Create a new record in an app.

$ kt create --app 1 --data '{"会社名": "New Startup Inc.", "担当者": "石原 達也", "ステータス": "初回接触", "電話番号": "03-1234-5678"}'

  Record created successfully
  App:        顧客管理 (App ID: 1)
  Record:     #12848
  Revision:   1
  Fields set: 会社名, 担当者, ステータス, 電話番号
  Timestamp:  2026-03-01 15:22:10 JST

kt update

Update an existing record.

$ kt update --app 1 --id 1042 --data '{"ステータス": "受注", "売上見込": 5800000}'

  Record updated successfully
  App:        顧客管理 (App ID: 1)
  Record:     #1042
  Revision:   14 → 15
  Changed:    ステータス (商談中 → 受注), 売上見込 (¥5,400,000 → ¥5,800,000)
  Timestamp:  2026-03-01 15:25:33 JST

kt search

Search across multiple apps with natural language.

$ kt search "overdue tasks assigned to Ishihara" --apps 5,12

  App: 案件管理 (ID: 5) — 3 matches
  #301  サーバー移行プロジェクト   期限: 2026-02-20  ステータス: 進行中
  #445  API連携開発                期限: 2026-02-25  ステータス: 進行中
  #512  セキュリティ監査対応       期限: 2026-02-28  ステータス: 進行中

  App: 日報アプリ (ID: 12) — 0 matches

  Total: 3 overdue records across 2 apps

kt bulk

Perform bulk operations on records.

$ kt bulk --app 1 --action update --query "ステータス = \"初回接触\" and 最終連絡 < \"2025-12-01\"" \
    --set '{"ステータス": "休眠"}'

  Bulk update preview:
  App:         顧客管理 (App ID: 1)
  Matching:    847 records
  Action:      Set ステータス → "休眠"

  Proceed? [y/N]: y

  Processing: [████████████████████████████████████████] 847/847

  Bulk update complete
  Updated:  847 records
  Failed:   0 records
  Duration: 12.3 seconds (9 API calls)

kt fields

Inspect the field schema of an app.

$ kt fields --app 1

  Field Code       Label         Type              Required  Unique
  ───────────────  ────────────  ────────────────  ────────  ──────
  会社名           会社名        SINGLE_LINE_TEXT  Yes       Yes
  担当者           担当者        USER_SELECT       Yes       No
  ステータス       ステータス    DROP_DOWN         Yes       No
  電話番号         電話番号      SINGLE_LINE_TEXT  No        No
  売上見込         売上見込      NUMBER            No        No
  最終連絡         最終連絡      DATE              No        No
  添付ファイル     添付ファイル  FILE              No        No
  備考             備考          MULTI_LINE_TEXT   No        No

  Total: 8 fields (+3 system fields: Record number, Creator, Updated)

kt export

Export records to a file.

$ kt export --app 1 --format csv --query "ステータス != \"休眠\"" --output ./customers_active.csv

  Exporting records from 顧客管理 (App ID: 1)
  Query:    ステータス != "休眠"
  Format:   CSV (UTF-8 with BOM for Excel compatibility)
  Records:  12,000 matching

  Downloading: [████████████████████████████████████████] 12,000/12,000

  Export complete
  File:     ./customers_active.csv
  Size:     4.2 MB
  Records:  12,000
  Columns:  8 fields + Record number

kt import

Import records from a file.

$ kt import --app 1 --file ./new_customers.csv --mode insert

  Import preview:
  App:        顧客管理 (App ID: 1)
  File:       ./new_customers.csv
  Mode:       Insert (new records only)
  Records:    250
  Validation: All 250 records pass schema validation

  Proceed? [y/N]: y

  Importing: [████████████████████████████████████████] 250/250

  Import complete
  Inserted: 250 records (#12849 - #13098)
  Skipped:  0
  Errors:   0

kt workflow

Manage process management (workflow) transitions.

$ kt workflow --app 5 --id 301 --action "承認"

  Workflow transition executed
  App:        案件管理 (App ID: 5)
  Record:     #301 (サーバー移行プロジェクト)
  Action:     承認
  Previous:   レビュー待ち → Assignee: 石原 達也
  Current:    承認済み → Assignee: 佐藤 花子
  Revision:   22 → 23
  Timestamp:  2026-03-01 16:05:44 JST

---

Workflow

  Developer                  kintone Agent                kintone API
  ─────────                  ─────────────                ───────────
      │                            │                           │
      │  kt records --app 1       │                           │
      │  --query "status=active"   │                           │
      ├───────────────────────────►│                           │
      │                            │  Parse & validate query   │
      │                            │  Translate field names     │
      │                            │                           │
      │                            │  GET /k/v1/records.json   │
      │                            ├──────────────────────────►│
      │                            │  {records: [...], total}  │
      │                            │◄──────────────────────────┤
      │                            │                           │
      │                            │  More pages? Auto-fetch   │
      │                            ├──────────────────────────►│
      │                            │◄──────────────────────────┤
      │                            │                           │
      │  Formatted table output    │  Merge & format results   │
      │◄───────────────────────────┤                           │
      │                            │                           │
      │  kt bulk --action update   │                           │
      ├───────────────────────────►│                           │
      │                            │  Count matching records   │
      │  "847 records. Proceed?"   │  Show preview             │
      │◄───────────────────────────┤                           │
      │  y                         │                           │
      ├───────────────────────────►│  Chunk into 100-record    │
      │                            │  batches, execute in      │
      │                            │  parallel (concurrency=5) │
      │                            ├──────────────────────────►│
      │                            │◄──────────────────────────┤
      │  "847 updated. 0 errors."  │  Aggregate results        │
      │◄───────────────────────────┤                           │

---

Error Handling

Error	Cause	Solution
520 CB_ILLEGAL_TOKEN: API token is invalid	Token does not have permission for the target app or is malformed	Regenerate the API token in the app's settings. Ensure the token has the required permissions (view, add, edit, delete).
409 CB_CONFLICT: Record revision mismatch	Another user modified the record between your read and update	Fetch the latest revision with kt records --app ID --id RECORD_ID, review changes, then retry with the current revision number.
400 CB_VA01: Missing required field	A required field was not included in the create/update payload	Use kt fields --app ID to check required fields. Include all required fields in your --data payload.
400 CB_VA01: Invalid field value	Value does not match field type (e.g., text in a NUMBER field)	Verify the field type with kt fields --app ID. Ensure numbers are unquoted, dates use YYYY-MM-DD, and dropdown values match exactly.
403 CB_NO02: No permission to proceed	User or token lacks permission for the requested operation	Check app permissions in kintone admin. API tokens are scoped per-app; you may need a separate token.
414 Request-URI Too Long	Query string exceeds URL length limit (common with in operator)	Break large in (...) clauses into multiple queries. Use bulk endpoint for large ID lists.
500 CB_IJ01: Internal server error	kintone server issue, often during heavy load or complex calculations	Retry after 30 seconds. If persistent, check Cybozu status page. Simplify CALC field dependencies if triggered by specific records.

---

FAQ

1. What is the difference between API token and password authentication? API tokens are scoped to individual apps and are the recommended method. Password auth grants access to all apps the user can access but requires username/password storage. Use API tokens for production; password auth for ad-hoc admin tasks.

2. Can I access multiple apps with one command? Yes. Provide comma-separated API tokens in KINTONE_API_TOKEN for multi-app access, or use password auth for cross-app operations.

3. How does the query syntax work? kintone uses its own query language: field_code operator "value". Example: ステータス in ("商談中", "提案済") and 売上見込 > 1000000 order by 最終連絡 desc.

4. What is the maximum number of records per bulk operation? 100 records per POST/PUT call, 500 IDs per DELETE call. The agent automatically chunks larger operations into batches.

5. Can I create new apps from the CLI? Yes. Use kt apps --create --name "New App" --fields ./schema.json to create an app with a predefined field schema. The agent handles preview and deployment.

6. How do I handle subtable (table) fields? Subtables are arrays of objects. In --data, provide them as: {"テーブル": [{"value": {"品名": {"value": "Widget"}, "数量": {"value": "10"}}}]}.

7. Does the agent support guest spaces? Yes. Set KINTONE_GUEST_SPACE_ID or use --guest-space ID per command. API endpoints are adjusted automatically.

8. Can I rollback a bulk update? kintone does not support native rollback. The agent creates a backup export before bulk operations (when --backup flag is used) so you can restore via kt import.

9. How do I handle file attachments? Upload: kt records --app 1 --id 42 --upload-file ./doc.pdf --field 添付ファイル. Download: kt records --app 1 --id 42 --download-field 添付ファイル.

10. What are kintone's API rate limits? kintone limits concurrent connections (typically 10 per domain) rather than requests-per-second. The agent manages connection pooling automatically.

11. Can I scaffold a kintone plugin project? Yes. kt plugin init --name "My Plugin" generates the full directory structure with manifest.json, config pages, and build scripts per Cybozu's specification.

12. How do I export data for BI tools? Use kt export --app ID --format csv for Tableau/Power BI, or --format json for custom pipelines. Add --scheduled for daily automated exports.

---

Data Storage

The kintone Agent maintains local state for efficient operations:

~/.kintone-agent/
├── config.yaml              # Domain, auth method, default app settings
├── cache/
│   ├── apps.json            # App list cache (TTL: 15 minutes)
│   ├── schemas/
│   │   ├── app_1.json       # Field schema cache per app (TTL: 1 hour)
│   │   └── app_5.json
│   └── query_history.json   # Recent queries for autocomplete
├── backups/
│   └── bulk_20260301_1.csv  # Pre-bulk-operation backup snapshots
├── logs/
│   ├── api-2026-03.log      # Monthly API log (tokens redacted)
│   └── bulk_operations.log  # Bulk operation audit trail
└── plugins/
    └── templates/           # Plugin scaffolding templates

Schema caches dramatically speed up validation and field resolution. Backups are created before destructive bulk operations and retained for 30 days. All authentication credentials are stored in the system keychain, never in plaintext files.

---

Comparison

Feature	kintone Agent	Airtable CLI	Notion CLI	Google Sheets CLI	Salesforce CLI
Japanese field names	Native UTF-8	Limited	Unicode	Unicode	Limited
No-code app builder	Full API	No	No	No	No
Workflow/process mgmt	Built-in	No	No	No	Apex required
Bulk operations	100/call native	10/call	Limited	Batch API	Bulk API 2.0
File attachments	Per-record	Per-record	Blocks	Drive link	Content
Subtables	Native	Linked records	Databases	No	Related lists
Plugin ecosystem	Cybozu marketplace	Extensions	Integrations	Add-ons	AppExchange
Guest space access	Native	Shared views	Shared pages	Shared sheets	Communities
On-premise option	Yes (cybozu.com)	No	No	No	Private Cloud
Query language	kintone QL	Formula	Filter API	Sheets formula	SOQL