Features of the Command Line Tool

Contents

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 (External link) 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 (External link) are available, such as:

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

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 (External link) .

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 (External link)

LICENSE

MIT License (External link)

Documentation

https://github.com/kintone/cli-kintone/blob/main/README.md (External link)

Notes

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 (External link) 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.

Option Description
--version Displays the version of cli-kintone
--help Shows help options
--base-url Required
The subdomain to be connected to. (Ex: https://example.kintone.com)
Must begin with https://
--app Required
The App ID to be connected to.
--api-token Required for some options
The API Token to authenticate with.
For authentication, either this option, or the username and password options are required.
If multiple API Tokens will be used, separate via a comma.
Ex:--api-token "BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL,WjfkaoKncXlXFqIY0lLwfv8FZELUkv8YnZRnV104"
--username Required for some options
The login name for the Kintone environment.
For authentication, either this option, or the username and password options are required.
Can be shortened to -u
--password Required for some options
The password for the Kintone environment.
For authentication, either this option, or the username and password options are required.
Can be shortened to -p
--attachments-dir Used when downloading from an attachment field to specify the output directory for the file.
--condition Used to specify a query to return specific records.
For more information on how to write queries, see Query string
--order-by Used to specify a query to order the records returned.
For more information on how to write queries, see Query string
--fields Used to specify specific fields to be exported. Fields should be separated by a comma ,
For example, returning only the "JoinDate" and "Division" fields would be written as: --fields "JoinDate,Division"
Fields within tables can not be specified in this manner.
When exporting fields from a table, the table's field code should be used, and all fields within that table will be exported.
--basic-auth-username When specified, the Kintone environment's username should be passed. Read more in the Basic Authentication article.
--basic-auth-password When specified, the Kintone environment's user password should be passed. Read more in the Basic Authentication article.
--guest-space-id If exporting from a guest space, the guest space ID should be passed here.
--encoding Specifies the encoding used for text strings. The default is utf-8
  • utf-8: utf-8
  • sjis: Shift-JIS
--pfx-file-path The Client Certificate Authentication feature is a legacy feature and is unavailable for Kintone domains running on the AWS platform.
--pfx-file-password The Client Certificate Authentication feature is a legacy feature and is unavailable for Kintone domains running on the AWS platform.
--proxy Used to specify a proxy server for sending requests.
When connecting via a proxy, pass this option along with the proxy server's URL and port number.
Specify it starting with https:// or http://.
If user authentication is required on the proxy server, specify the authentication credentials in the format of username:password@ before the proxy server's address.
Example: --proxy http://username:password@proxy_server_address:port_number

Import

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

Option Description
--version Displays the version of cli-kintone
--help Shows help options
--base-url Required
The subdomain to be connected to. (Ex: https://example.kintone.com)
Must begin with https://
--app Required
The App ID to be connected to.
--api-token Required for some options
The API Token to authenticate with.
For authentication, either this option, or the username and password options are required.
If multiple API Tokens will be used, separate via a comma.
Ex:--api-token "BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL,WjfkaoKncXlXFqIY0lLwfv8FZELUkv8YnZRnV104"
--username Required for some options
The login name for the Kintone environment.
For authentication, either this option, or the username and password options are required.
Can be shortened to -u
--password Required for some options
The password for the Kintone environment.
For authentication, either this option, or the username and password options are required.
Can be shortened to -p
--update-key The field code to used as a key for bulk adding or updating.
The following fields can be used:
  • Record Id
  • The following fields if the prohibit duplicate values option is enabled:
    • Text Field
    • Number Field
--file-path Required
The path to the file to be imported.
Only .csv files are supported.
--attachments-dir Used when uploading to an attachment field to specify the file to be attached.
--fields Used to specify specific fields to be imported. Fields should be separated by a comma ,
For example, returning only the "JoinDate" and "Division" fields would be written as: --fields "JoinDate,Division"
--basic-auth-username When specified, the Kintone environment's username should be passed. Read more in the Basic Authentication article.
--basic-auth-password When specified, the Kintone environment's user password should be passed. Read more in the Basic Authentication article.
--guest-space-id If exporting from a guest space, the guest space ID should be passed here.
--encoding Specifies the encoding used for text strings. The default is utf-8
  • utf-8: utf-8
  • sjis: Shift-JIS
--proxy Used to specify a proxy server for sending requests.
When connecting via a proxy, pass this option along with the proxy server's URL and port number.
Specify it starting with https:// or http://.
If user authentication is required on the proxy server, specify the authentication credentials in the format of username:password@ before the proxy server's address.
Example: --proxy http://username:password@proxy_server_address:port_number

Deletion

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

Option Description
--version Displays the version of cli-kintone
--help Shows help options
--base-url Required
The subdomain to be connected to. (Ex: https://example.kintone.com)
Must begin with https://
--app Required
The App ID to be connected to.
--api-token Required for some options
The API Token to authenticate with.
For authentication, either this option, or the username and password options are required.
If multiple API Tokens will be used, separate via a comma.
Ex:--api-token "BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL,WjfkaoKncXlXFqIY0lLwfv8FZELUkv8YnZRnV104"
--file-path Required
The path to the file to be imported.
Only .csv files are supported.
--yes By passing this option, the delete confirmation prompt will be skipped.
Can be shortened to -y
--basic-auth-username When specified, the Kintone environment's username should be passed. Read more in the Basic Authentication article.
--basic-auth-password When specified, the Kintone environment's user password should be passed. Read more in the Basic Authentication article.
--guest-space-id If exporting from a guest space, the guest space ID should be passed here.
--encoding Specifies the encoding used for text strings. The default is utf-8
  • utf-8: utf-8
  • sjis: Shift-JIS
--pfx-file-path The Client Certificate Authentication feature is a legacy feature and is unavailable for Kintone domains running on the AWS platform.
--pfx-file-password The Client Certificate Authentication feature is a legacy feature and is unavailable for Kintone domains running on the AWS platform.
--proxy Used to specify a proxy server for sending requests.
When connecting via a proxy, pass this option along with the proxy server's URL and port number.
Specify it starting with https:// or http://.
If user authentication is required on the proxy server, specify the authentication credentials in the format of username:password@ before the proxy server's address.
Example: --proxy http://username:password@proxy_server_address:port_number

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 (External link) article.
  • The Client Certificate Authentication feature is a legacy feature and is unavailable for Kintone domains running on the AWS platform.
  • By passing the --basic-auth-username and --basic-auth-password options to cli-kintone, basic authentication can be used. Kintone environments that run on a kintone.com domain though will not be able to use the basic authentication feature. 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 (External link) 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 (External link) .

  • 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.

information

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: