Features of the Command Line Tool
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
Documentation
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.
|
|
--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 Tokensarticle 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.
|
|
--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
|
|
Example
|
|
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. (e.g. 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. e.g. --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
|
--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. (e.g. 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. e.g. --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:
|
--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
|
--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. (e.g. 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. e.g. --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
|
--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:
- 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
-
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
.
- 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
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 September 2024, on cli-kintone Version 1.11.0
Feedback for cli-kintone
Feedback can be created in the Issues of the GitHub repository: