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 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 is 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 to modified software are not available for official support.
GitHub
https://github.com/kintone/cli-kintone
LICENSE
Documentation
https://github.com/kintone/cli-kintone/blob/main/README.md
Notes
Installation
Download the cli-kintone executable
The cli-kintone executable can be downloaded via GitHub for Windows / macOS / Linux.
- Access
GitHub Releases
- From the Assets section, download one of the following:
- Windows:
cli-kintone-win.zip
- Linux:
cli-kintone-linux.zip
- macOS:
cli-kintone-macos.zip
- Windows:
- Unzip the file, and place the contents in a directory of your choosing
Run via the command prompt (for Windows users)
Open a command prompt via the following steps. The command prompt is necessary to use cli-kintone.
-
While holding the windows key, press the R key. A prompt asking which program to run will appear.
-
In the name field, enter "cmd" and click OK. The command prompt will open.
-
Using the
cd
command, navigate to the folder containing the cli-kintone.exe file1 2
# Changing the directory to where the cli-kintone.exe files is located cd Desktop\works
Check the version of cli-kintone
Check the version of cli-kintone.
|
|
If the downloaded version is displayed correctly, continue with the tutorial.
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. More information can be found on the Generating API Tokenshelp article.
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 display records, use the record export
command.
In addition, specify the Kintone domain and App ID via the --base-url
and --app
options.
--base-url
: The subdomain to retrieve records from. (ex: https://www.example.kintone.com)
--app
: The App ID to retrieve records from. (ex: 123)
When the command is run, the record information will be output in a CSV format. The headers of the CSV will be the field codes specified within the App.
Example
|
|
Export to a CSV file
In the command prompt or shell, the redirect function (>
) can be used to pipe the output into a file.
Example
|
|
Exporting with queries or parameters
The --condition
option and the --order-by
option can be used to specify and order records.
For more information on queries, refer to the
Query string article.
|
|
--condition
option: a query for filtering data.--order-by
option: a query for ordering data.
Example
|
|
Downloading attachments
To retrieve files attached to records, the --attachments-dir
option along with the directory to download to must be specified.
The directory file path is relational to the directory cli-kintone is run from.
|
|
--attachments-dir
: The directory to which the attachment will be downloaded to.
Example
|
|
When run, the attachments will be downloaded to the specified directory.
For every record in the output, a directory with the name structure of fieldCode-RecordNumber
will be created, with the files included inside.
|
|
Exporting Tables
As stated in the
Additional Notes on Exported Files
article of the Kintone Help, table data from each record will be exported into multiple rows.
In the file, each record is composed of a line with "*" symbol in the first column, and its subsequent lines without the "*" symbol.
Example
|
|
Importing Data
To add or update record data, use the record import
command.
In addition, specify the Kintone domain and App ID via the --base-url
and --app
options.
--base-url
: The Kintone subdomain name (ex: https://example.kintone.com)--app
: App ID(ex: 123)
Adding Records
A file path can be specified via the --file-path
option.
|
|
--file-path
: The file path of a CSV file with information to add or update records.
The first row of the CSV file are headers. Each header should correlate to the field code of the value to be updated.
CSV File Example
|
|
When the command is run, the number of records added will be output to the command prompt.
Example
|
|
Adding or Updating Records with an Update Key
By passing the --update-key
option with a valid field code, records can be updated simultaneously.
Valid fields for the --update-key
option are as follows:
- Record ID
- The following fields with "Prohibit duplicate values" enabled
- Text
- Number
|
|
The field specified in the --update-key
option and values which match the columns in the CSV file specified will be overwritten.
Non-matching values will be added as new records.
--update-key
: The field code to act as the key to simultaneous updating.
When the command is run, the number of records added or updated will be output.
Example
|
|
Importing Attachments
Attaching a File
To upload and attach files, pass the --attachments-dir
option along with the relative directory path containing the files to be attached.
In the CSV file containing record data, specify the path to the attachment file. The path is relative to the specified --attachments-dir
path. If one attachment field will have multiple uploads, separate the file names with new lines.
Example
|
|
When the command is run, the number of records added or updated will be output.
Example
|
|
Deleting Attached Files
To delete an attachment, leave the attachment field value blank.
Example CSV
|
|
Example
|
|
Adding or Updating Records in a Table
Records that contain tables are set as multiple lines within the CSV file, which can be referenced in the
Additional Notes on Exported Files
help article.
Within the CSV file, set the header name of the first column with an "*" symbol. The beginning of each record's data is marked with the "*" symbol in this first column. The first column of the subsequent lines representing rows of the tables are to be left blank.
Warning
Note on updating tables in existing records
- Ensure that rows that will not be updated are also contained in the CSV file. As tables are completely overwritten on import, any existing rows in the table not included in the import file will be lost.
- When there is a table within which only a portion will be updated, use either of the following methods to update.
Failure to do so will replace the existing table fields with empty fields.
- Add the row ID for data to the CSV file The row ID can be checked when Exporting a Table in the table field.
- Recreate the entire table in the import CSV, and overwrite the table.
Example
|
|
Example
|
|
Deleting Data
Attention
Records deleted with the record delete
command can not be recovered.
To delete records, specify the record delete
command.
In addition, specify the Kintone domain and App ID via the --base-url
and --app
options.
--base-url
: The subdomain to retrieve records from. (ex: https://www.example.kintone.com)
--app
: The App ID to retrieve records from. (ex: 123)
Delete All Records
To delete all records, run the command without passing the --file-path
option.
|
|
Example
|
|
Deleting Specific Records
To delete specific records, specify the record IDs to be deleted in the CSV file passed to the --file-path
option.
--file-path
: The file path of a CSV file with information to update or add records.
|
|
The first row of the CSV file must be a header, with the field code of the record ID field.
The second row must contain either the record IDs to be deleted, or the
App Code
containing the Record IDs to be deleted.
Example
|
|
When the command is run, a message to confirm the deletion will be output.
To begin deletion, enter "Y" and submit via the Enter
key. In order to cancel the operation, input "N" instead.
If the --yes
or -y
option is passed to the command, the specified records will be deleted without confirmation.
Example
|
|
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
|
--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 |
When connecting via a proxy, pass this option along with the proxy server's URL and support number. Must begin with https:// or http:// .Proxies which require authentication are not supported. |
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:
|
--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 |
When connecting via a proxy, pass this option along with the proxy server's URL and support number. Must begin with https:// or http:// .Proxies which require authentication are not supported. |
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
|
--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 |
When connecting via a proxy, pass this option along with the proxy server's URL and support number. Must begin with https:// or http:// .Proxies which require authentication are not supported. |
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.
- 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.
Changelog
The latest information on cli-kintone can be found at 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 2023/05, on cli-kintone Version 1.5.1
Feedback for cli-kintone
Feedback can be created in the Issues of the GitHub repository: