Overview

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. Read through the installation guide for steps on preparing cli-kintone for the local environment.

Besides importing and exporting records, many other functions which are not possible via the GUI are 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 Features of the Command Line Tool (v0) article.

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

Support

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 .

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.

GitHub

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

LICENSE

MIT License

Documentation

https://github.com/kintone/cli-kintone/blob/main/README.md

Notes

• Handling large amounts of records may affect the performance of Kintone.

Installation

Refer to the cli-kintone Installation article.

Authentication

Using API Token Authentication

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 Generating API Tokens article on the Kintone Help site.

The examples in this tutorial use API Authentication.

Using Password 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.

Exporting Data

To export data, use the record export command.

For more information, refer to the Export Data with the Command Line Tool article.

Downloading attachments

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

For more information, refer to the Download and Upload Attachments with the Command Line Tool

Importing Data

To import data, use the record import command.

For more information, refer to the Import Data with the Command Line Tool article.

Attaching a File

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

For more information, refer to the Download and Upload Attachments with the Command Line Tool

Deleting Attached Files

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

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

Deleting Data

To delete records, use the record delete command.

For more information, refer to the Delete Data with the Command Line Tool article.

List of Options

For versions prior to v1.0.0, a list of options can be found in the Features of the Command Line Tool (v0) article.

Export

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

Import

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

Deletion

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

Limitations

Field Limitations

• The following fields can only be specified when adding records: Note: An API Token with Manage app Permissions, or a user account with App Administrator Permissions must be used when running the command.
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
• The following fields can not be exported:
  • Status
  • Created by
  • Categories
• 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

Other Limitations

• 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, check the Managing IP Address Restrictions article.
• The Client Certificate Authentication feature is a legacy feature and is unavailable for Kintone domains running on the AWS platform.
• 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, read the Basic Authentication article.

Debugging Errors

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.

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.

Change Log

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

• March 2nd 2023: Article updated with the delete command parameters
• October 1st 2022: Article Published

Differences between v0 and v1

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 Differences between cli-kintone v1.x.x and v0.x.x article.

The sample code in this article is current as of May 2023, on cli-kintone Version 1.5.1

Feedback for cli-kintone

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

• Github