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

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

Download the cli-kintone executable

The cli-kintone executable can be downloaded via GitHub for Windows / macOS / Linux.

1. Access GitHub Releases
2. From the Assets section, download one of the following:
   • Windows: cli-kintone-win.zip
   • Linux: cli-kintone-linux.zip
   • macOS: cli-kintone-macos.zip
3. 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.

1. While holding the windows key, press the R key. A prompt asking which program to run will appear.

2. In the name field, enter "cmd" and click OK. The command prompt will open.

3. Using the cd command, navigate to the folder containing the cli-kintone.exe file

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

1
2
3
4

cli-kintone.exe --version

# The version number will be output.
1.0.0

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.

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. More information can be found on the Generating API Tokens help article.

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

1
2
3
4
5
6
7

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

# Resulting Output
"Record Number","EmployeeId","Name","JoinDate","Division","Creation Date","Creation Time","Updated","Update Time"
"2","0002","Helen Gensler","2021-01-01","General Affairs","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"
"1","0001","Tom Stevens","2020-01-01","General Affairs","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"

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

1
2
3

# Outputting to a file named "records.csv"
cli-kintone.exe record export --base-url https://example.kintone.com --app 123 ^
  --api-token BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL > records.csv

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.

1
2
3

cli-kintone.exe record export --base-url https://example.kintone.com --app APP_ID ^
  --api-token API_TOKEN ^
  --condition "QUERY_STRING" --order-by "ORDER_STRING"

• --condition option: a query for filtering data.
• --order-by option: a query for ordering data.

Example

1
2
3
4
5
6
7
8
9

# A query for ordering employees by their employment date, specified as "JoinDate"
cli-kintone.exe record export --base-url https://example.kintone.com --app 123 ^
  --api-token BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL ^
  --condition "JoinDate >= \"2014-01-01\"" --order-by "JoinDate asc"

# Resulting Output
"Record Number","EmployeeId","Name","JoinDate","Division","Creator","Created DateTime","Updater","Updated DateTime"
"1","0001","Tom Stevens","2020-01-01","General Affairs","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"
"2","0002","Helen Gensler","2021-01-01","General Affairs","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"

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.

1
2
3

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

• --attachments-dir: The directory to which the attachment will be downloaded to.

Example

1
2
3
4
5
6
7
8
9

# The file will be output to the attachments directory, which is contained in the same directory as the cli-kintone executable
cli-kintone.exe record export --base-url https://example.kintone.com --app 123 ^
  --api-token BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL ^
  --attachments-dir ./attachments

# Resulting Output
"Record Number","EmployeeId","Name","JoinDate","Division","Photo","Creator","Created DateTime","Updater","Update DateTime"
"2","0002","Helen Gensler","2021-01-01","General Affairs","helen-gensler.png","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"
"1","0001","Tom Stevens","2020-01-01","General Affairs","tom-stevens.png","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"

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.

1
2
3
4
5
6

works # location of the cli-kintone executable
└─── attachments
    ├── Photo-1
    │    └── tom-stevens.png
    └── Photo-2
          └── helen-gensler.png

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

1
2
3
4
5
6
7
8

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

# Resulting Output
*,"Record Number","EmployeeId","Name","JoinDate","Division","AssignInformation","AssignDate","AssignDivision","Creator","Created DateTime","Updater","Updated DateTime"
*,"2","0001","Helen Gensler","2021-01-01","General Affairs","3705","2021-01-01","General Affairs","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"
*,"1","0001","Tom Stevens","2020-01-01","General Affairs","3703","2020-01-01","Sales Division","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"
,"1","0001","Tom Stevens","2020-01-01","General Affairs","3702","2021-01-01","General Affairs","Administrator","2022-07-12T01:49:00Z","Administrator","2022-07-12T01:49:00Z"

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.

1
2
3

cli-kintone.exe record import --base-url https://example.kintone.com --app APP_ID ^
  --api-token API_TOKEN ^
  --file-path FILE_PATH

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

1
2
3

"EmployeeId","Name","JoinDate","Division"
"0004","Helen Gensler","2020-04-01","Planning Division"
"0003","Tom Stevens","2020-04-01","HR"

When the command is run, the number of records added will be output to the command prompt.

Example

1
2
3
4
5
6

cli-kintone.exe record import --base-url https://example.kintone.com --app 123 ^
  --api-token BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL ^
  --file-path ./example.csv

[2023-02-01T06:12:06.505Z] INFO: Starting to import records...
[2023-02-01T06:12:07.751Z] INFO: Imported 2 records successfully

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

1
2
3
4

cli-kintone.exe record import --base-url https://example.kintone.com --app APP_ID ^
  --api-token API_TOKEN ^
  --file-path FILE_PATH ^
  --update-key FIELD_CODE

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

1
2
3
4
5
6
7
8

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

[2023-02-01T06:12:05.920Z] INFO: Preparing to import records...
[2023-02-01T06:12:06.505Z] INFO: Starting to import records...
[2023-02-01T06:12:07.751Z] INFO: Imported 2 records successfully

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

"EmployeeId","Name","JoinDate","Division","Photo"
"0004","Helen Gensler","2020-04-01","Planning Division,"helen-gensler.png"
"0003","Tom Stevens","2020-04-01","HR","tom-stevens.png
tom-stevens-cat.png"```

**Example Directory Structure**

```shell
works # Directory containing cli-kintone.exe
└── attachments
  ├── helen-gensler.png
  ├── tom-stevens.png
  └── tom-stevens-cat.png

When the command is run, the number of records added or updated will be output.

Example

1
2
3
4
5
6
7

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

[2023-02-01T06:19:00.671Z] INFO: Starting to import records...
[2023-02-01T06:19:01.475Z] INFO: Imported 2 records successfully

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

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

1
2
3
4

"*","EmployeeId","Name","JoinDate","Division","AssignInformation","AssignDate","AssignDivision"
"*","0004","Helen Gensler","2020-04-01","Planning Division","3705","2020-04-01","Planning Division"
"*","0003","Tom Stevens","2020-04-01","HR","3703","2020-04-01","HR"
"","0005","Rachel Arnolds","2020-04-01","Sales","3702","2022-04-01","Sales"

Example

1
2
3
4
5
6

cli-kintone.exe record import --base-url https://example.kintone.com --app 123 ^
  --api-token BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL ^
  --file-path ./example.csv

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

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.

1
2

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

Example

1
2
3
4
5
6

cli-kintone.exe record delete --base-url https://example.kintone.com --app 123 ^
  --api-token BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL

? Are you sure want to delete records? Yes
[2023-02-27T07:20:29.148Z] INFO: Starting to delete all records...
[2023-02-27T07:20:29.632Z] INFO: 50 records are deleted successfully

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.

1
2
3

cli-kintone.exe record delete --base-url https://example.kintone.com --app APP_ID ^
  --api-token API_TOKEN ^
  --file-path FILE_PATH

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

1
2
3

"RecordId"
"sampleApp-1"
"sampleApp-2"

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

1
2
3
4
5
6

cli-kintone.exe record delete --base-url https://example.kintone.com --app 123 ^
  --api-token BNk5wfOufWtPSTc6miMBTEa0SEm5ZokIcJWSSYXL ^
  --file-path ./example.csv -y

[2023-02-27T06:09:00.243Z] INFO: Starting to delete records...
[2023-02-27T06:09:00.938Z] INFO: 2 records are deleted successfully

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

• Github