This article introduces features of the Kintone Command Line Tool a.k.a. cli-kintone. cli-kintone is a tool to import and export record data to and from a Kintone App.

Other functions, which are not possible via the GUI when adding/updating records in bulk, are also available such as:

• Simultaneously downloading all attached files from a record
• Simultaneously attaching multiple files to a record

This article introduces the basic features of cli-kintone as of version 1.0.0. For versions before v1.0.0, refer to the following article.

(End-of-Support) Features of the Command Line Tool (v0)

All examples in this article are shown using the Windows Command Prompt. For other environments, adjust file names, and the environment PATH as necessary.

cli-kintone is developed and supported by Cybozu for use in production environments. Technical support for cli-kintone versions v1.0.0 and above are handled via GitHub Issues.
cli-kintone GitHub Issues

Changes to the source code or redistribution are permitted in accordance with the included LICENSE file. Please confirm the type and scope of the LICENSE via the client library or GitHub repository. Note that bugs or errors in modified software are not available for official support.

https://github.com/kintone/cli-kintone

MIT License

cli-kintone

Handling large amounts of records may affect the performance of Kintone. For more details, refer to the following article:
Kintone Coding Guidelines : Consider the Effect to the Kintone Service

Read through the following article for steps on preparing cli-kintone for the local environment:

Install the Command Line Tool

To use an API Token for authentication, specify the --api-token option.

1
2

cli-kintone.exe record export --base-url https://example.kintone.com --app APP_ID ^
  --api-token API_TOKEN

• --api-token: API Token (ex: BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL) Ensure that the appropriate permissions are granted for the API Token. For example, to display records using an API Token, the View records permission must be granted via the API Token settings. For more information, refer to the following article on the Kintone Help site:
  Generating API Tokens

The examples in this tutorial use API Authentication.

To use password authentication, specify the --username and --password options.

1
2

cli-kintone.exe record export --base-url https://example.kintone.com --app APP_ID ^ 
  --username USER_NAME --password USER_PASSWORD

• --username: The login name for the Kintone environment. Can be shortened to -u.
• --password: The password for the Kintone environment. Can be shortened to -p.

To export data, use the record export command.

For more information, refer to the following article:

Export Data with the Command Line Tool

To retrieve files attached to records, use the record export command along with the --attachments-dir option.

For more information, refer to the following article:

Download and Upload Attachments with the Command Line Tool

To import data, use the record import command.

For more information, refer to the following article:

Import Data with the Command Line Tool

To upload and attach files, use the record import command along with the --attachments-dir option.

For more information, refer to the following article:

Download and Upload Attachments with the Command Line Tool

To delete an attachment, leave the attachment field value blank.

Example CSV

1
2

"EmployeeId","Name","JoinDate","Division","Photo"
"0004","Helen Gensler","2020-04-01","Planning Division,""

Example

1
2
3
4
5
6
7
8
9

cli-kintone.exe record import --base-url https://example.kintone.com --app 123 ^
  --api-token BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL ^
  --file-path ./example.csv ^
  --update-key "EmployeeId" ^
  --attachments-dir ./attachments

[2024-09-09T06:23:43.147Z] INFO: Preparing to import records...
[2024-09-09T06:23:43.498Z] INFO: Starting to import records...
[2024-09-09T06:23:44.243Z] INFO: Imported 1 records successfully

To delete records, use the record delete command.

For more information, refer to the following article:

Delete Data with the Command Line Tool

For versions prior to v1.0.0, a list of options can be found in the "Display Cli-kintone Options" section of the following article:

Features of the Command Line Tool (v0)

By passing the --help option after the record export command, a list of export options will be output.

By passing the --help option after the record import command, a list of import options will be output.

By passing the --help option after the record delete command, a list of deletion options will be output.

• The following fields can only be specified when adding records:

  • Created by
  • Created datetime
  • Updated by
  • Updated datetime

  *Note: An API Token with Manage app Permissions, or a user account with App Administrator Permissions must be used when running the command.

• The following fields can not be exported:

  • Status
  • Created by
  • Categories
  • Related records

• The following fields, even if imported, will not reflect the updated values:

  • Fields copied via the Lookup field
  • Calculated
  • Text fields with the calculate automatically feature enabled
  • Status
  • Created by
  • Categories
  • Related records

• If the Kintone environment has IP Address access restrictions, the IP address from which cli-kintone will be run can be added to the IP whitelist. For more information, refer to the following link:
  How to Manage Kintone's Login Security Settings
• The Client Certificate Authentication feature is a legacy feature and is unavailable for Kintone domains running on the AWS platform. For more information, refer to the following news:
  API Updates for September 2019
• Previously, by passing the --basic-auth-username and --basic-auth-password options to cli-kintone, basic authentication could be used. However, as of June 2020, Basic Authentication has been deprecated, and is no longer available for use. For more information, refer to the following article:
  Basic Authentication

If any errors occur, check the logs that are outputted into the console.

Problems can also be identified by checking the Audit Log in the System Administration page. For more information, refer to the following article on the Kintone Help site:

Viewing Audit Logs

Click the gear icon on the upper right menu of Kintone, and navigate to User & System Administration -> Audit Logs -> View & Download.

From the Audit Log list, it is possible to see what record operations were performed. Their success/failure as well as the details of each operation can be seen by clicking the information icon on the left side of the table.

Looking at this information allows the user to see if requests from cli-kintone are successfully reaching their Kintone environment. Use this information to find causes of any particular issues and debug them.

The latest information on cli-kintone can be found in the Change Log.

Change Log

• May 1st 2023: Article updated with information about proxy authentications, which was added in v1.4.0
• March 2nd 2023: Article updated with the delete command parameters
• October 1st 2022: Article Published

cli-kintone versions 1.0.0 and after have support for bulk updating and adding. For a comprehensive list of differences between previous versions, refer to the following article:

Differences between cli-kintone v1.x.x and v0.x.x

The sample code in this article is current as of September 2024, on cli-kintone Version 1.11.0

Feedback can be created in the Issues of the GitHub repository:

• cli-kintone GitHub Issues