Features of the Command Line Tool (v0)

cli-kintone v0

Overview
Display Cli-kintone Options
Authentication
Export data
Import Data
Limitations
Releases

Overview

This article introduces features of the Kintone Command Line Tool v0 a.k.a. cli-kintone v0. Cli-kintone is a tool to import and export record data to and from a Kintone App. Read through Set Up the Command Line Tool (v0) for steps on preparing cli-kintone for the local environment.

Attention

As of October 31, 2023, support for cli-kintone v0 has ended. For the latest features and security support it is highly recommended to upgrade to cli-kintone v1.

For more information, refer to the End of Support Notice for cli-kintone v0.

Display Cli-kintone Options

Running cli-kintone without any arguments will list the available cli-kintone options.

Options	Description	Example
--export	To be used when exporting data out from Kintone. Data will be exported to the stdout (i.e. it will display on the console)
--import	To be used when importing data into Kintone. Data will be imported from the stdin. If the -f option is also specified, data is imported from the specified file instead.
-d	The domain name. Specify the FQDN of the Kintone environment, such as "example.kintone.com". This option is required.	`-d example.kintone.com`
-a	The App ID of the Kintone App. The App ID can be found in the URL of the App e.g. https://example.kintone.com/k/27/ This option is required.	`-a 27`
-u	The login name of the Kintone user to authenticate with. Either the API token or the login name is required.	`-u john-doe@kintone.com`
-p	The login password for the Kintone user.	`-p password`
-t	The API token of the App. Either the API token or the login name is required.	`-t 4gp63Dpol3ksp4S3fd`
-g	The Guest Space ID. Required, if the App lies within a Guest Space. The Guest Space ID can be found in the URL of the App e.g. https://example.kintone.com/k/guest/3/44/	`-g 3`
-o	The export format. Specify "json" or "csv". Default is "csv".	`-o json`
-e	The Encoding format. Specify "utf-8", "utf-16", "utf-16be-with-signature", "utf-16le-with-signature", "sjis" or "euc-jp". Default is "utf-8".	`-e utf-16`
-U	The Basic Authentication login name. The Basic Authentication feature is a legacy feature, and is unavailable as of June 2020.	`-U basicusername`
-P	The Basic authentication password.	`-P basicuserpassword`
-q	The query for the API call. Refer to Get Record for information on how to write queries.	`-q "duedate < \"2017-04-27\" order by task_status"`
-c	The fields to export. Specify the field codes of the fields, and separate them with commas.	`-c "title, name, date"`
-f	The file name, for importing data.	`-f /Documents/mydata.csv`
-b	The directory to download attachment files to, or to upload files from.	`-b /Documents/2017Oct`
-l	Position index of data in the input file. Data import will start from this line.	`-l 11`
-D	If this option is specified when importing data, cli-kintone will delete all existing records inside the App before importing.	`-D`

Below are examples of using cli-kintone on Windows. To cancel a process while it's running, press CTRL+C.

Authentication

Authenticate via a username and password

Use the -u option to authenticate via a username and password. For authenticating with the user Krispy:

1
2


> cli-kintone.exe --export -a 999 -d example.kintone.com -u Krispy
Password:

The user is prompted to enter a password.

Authenticate via an API token

Use the -t option to authenticate via an API Token. Refer to API Tokens for how to generate an API token for the Kintone App. Make sure to grant the appropriate permissions to the API token. For authenticating with an API Token of "c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3":

1

> cli-kintone.exe --export -a 999 -d example.kintone.com -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3

Export data

Export Record Data to the console

To export data to the console from a Kintone App, specify the Kintone FQDN with the -d option, and the App ID with the -a option. For an FQDN of "example.kintone.com" and App ID of 999:

1
2


> cli-kintone.exe --export -a 999 -d example.kintone.com -u Krispy
Password:

The result will be exported in CSV format:

1
2
3
4
5


"$id","Record_number","Created_datetime","Created_by","Hired_Date","Department","Updated_datetime","Updated_by","Name"
"4","4","2017-10-01T08:01:00Z","Krispy","2017-04-04","President’s office","2017-10-01T08:01:00Z","Krispy","David Walker"
"3","3","2017-10-01T08:01:00Z","Krispy","2015-04-03","Developer","2017-10-01T08:01:00Z","Krispy","Adam Clark"
"2","2","2017-10-01T08:01:00Z","Krispy","2014-04-02","General Affairs","2017-10-01T08:01:00Z","Krispy","John Lewis"
"1","1","2017-10-01T08:01:00Z","Krispy","2012-04-01","Sales","2017-10-01T08:01:00Z","Krispy","Sarah Jones"

To export the result in JSON format, specify "-o json".

Export with character encoding

By default, the character encoding is UTF-8. Use the -e option to specify a different character encoding:

1

> cli-kintone.exe --export -a 999 -d example.kintone.com -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3 -e utf-16

Specify the fields to export

By default, all fields of the App are exported. Use the -c option to specify the fields to export. For exporting the fields with field codes of record_num, Name, and Department:

1

> cli-kintone.exe --export -a 999 -d example.kintone.com -u Krispy -c "record_num,Name,Department"

The result will be exported as below:

1
2
3
4
5


"record_num","Name","Department"
"4","David Walker","President’s office"
"3","Adam Clark","Development"
"2","John Lewis","General Affairs"
"1","Sarah Jones","Sales"

Export data with queries and sorting

The -q option specifies the filter and sort of the exported data. Refer to the Query string article for information on how to write queries. For exporting records where the date field with field code Hired_date is before April 27th 2017:

1

> cli-kintone.exe --export -a 999 -d example.kintone.com -u Krispy -c "record_num,Name,Hired_Date" -q "Hired_Date < \"2017-04-27\" order by Hired_Date asc

The result will be exported as below:

1
2
3
4


"record_num","Name","Hired_Date"
"1","Sarah Jones","2012-04-01"
"2","John Lewis","2014-04-02"
"3","Adam Clark","2015-04-03"

Export table data

If the exported record data contains table data, the contents of the record will be displayed in multiple lines. Below is how the exported CSV data looks like, together with data of other records:

1
2
3
4
5
6
7


*,"$id","Name","Hired_Date","Department","Transferred_Date","Transferred_to"
*,"5","James Smith","2010-04-01","Sales","2011-04-15","General Affairs"
,"5","James Smith","2010-04-01","Sales","2016-09-21","Sales"
*,"4","David Walker","2017-04-04","President's office",,
*,"3","Adam Clark","2015-04-03","Plannnig",,
*,"2","John Lewis","2014-04-02","","2017-05-24","General Affairs"
*,"1","Sarah Jones","2015-08-18","HR",,

In this example, the fields Transferred_Date and Transferred_to are in a table, and can carry several lines of data. If exported records contain table data, an * symbol that indicates new records will be added to the first column of every record of the exported file. Exported rows without an * symbol indicate that they carry the data of the second or later rows of a table (the data of the first row of the table is carried by the row containing the * symbol).

In the above CSV data, 5 records are exported. Record number 5 contains two lines of data in its table, which is represented in the CSV as two rows.

The contents of Record number 5 on the Kintone GUI display as below:

Download attachments

Specify the folder name to download the file into using the -b option. The folder is automatically created if the name does not exist. For exporting files attached to the field with the field code of pic into the folder kintonePics:

1

> cli-kintone.exe --export -a 999 -d example.kintone.com -u Krispy -c "record_num,Name,pic" -b kintonePics

New folders will be created inside the specified folder for each record that contains attachment files. These new folders will be named as "{attachment field code}-{record number}".

In the exported console data, the value of the attachment file field will be the relative path from the specified download folder.

1
2
3
4
5
6


"record_num","Name","pic"
"5","James Smith","pic-5\img0032.jpg"
"4","David Walker","pic-4\img3321.jpg"
"3","Adam Clark","pic-3\img2506.jpg"
"2","John Lewis","pic-2\img0024.jpg"
"1","Sarah Jones","pic-1\img1543.jpg"

Export to a CSV file

The > symbol can be used to redirect the output to a file. Note that this command is not part of cli-kintone's feature, but it is a common function offered by command line interfaces. The usage or output may differ depending on what operating system is being used. The following command redirects cli-kintone's output to a csv file:

1

> cli-kintone.exe --export -a 999 -d example.kintone.com -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3 > sample.csv

Import Data

Import data using a CSV file

Use the -f option to specify a file to import into the App. Prepare a CSV file with data such as:

1
2


"Name","Department","Hired Date"
"Mason Miller","Sales","2017-10-01"

For adding CSV data of sample.csv to a Kintone App:

1

> cli-kintone.exe --import -a 999 -d example.kintone.com -u Krispy -f sample.csv

The resulting data will be displayed on the console:

1
2
3
4
5
6
7


"$id","Name","Department"
"6","Mason Miller","Sales"
"5","James Smith","Sales"
"4","David Walker","President's office"
"3","Adam Clark","Plannnig"
"2","John Lewis","General Affairs"
"1","Sarah Jones","HR"

Import data after deleting existing data

If you specify the -D option, all existing records are deleted before importing data.

Update data using a CSV file

To update existing data, add an $id column (which represents the record ID) in the CSV file which will be the key to update. Following is a sample CSV file that updates Clark’s department to the Planning Dept. and Jones’s to the HR Dept.

1
2
3


"$id","Name","Department"
"3","Adam Clark","Planning"
"1","Sarah Jones","HR"

This will be used to update as follows:

1

> cli-kintone.exe --import -a 999 -d example.kintone.com -u Krispy -f updatedata.csv

To update records using a different field as the key instead of the record number, add an * symbol to the field code name to indicate it will be the key. The key field must have the Prohibit duplicated values settings checked in the Kintone App settings. For updating data in an App with the field code customerCode as the key field, prepare a CSV file with data such as:

1
2
3


"*customerCode","Name","Department"
"0001","Adam Clark","Planning"
"0002","Sarah Jones","HR"

This will be used to update as follows:

1

> cli-kintone.exe --import -a 999 -d example.kintone.com -u Krispy -f sample.csv

Import table data

Similar to the exported table data, rows with an * symbol will be treated as new records, and rows without an * symbol will be treated as containing table data related to the rows above it. Non-table Values of the rows that do not have an * in the first column will be ignored.

Uploading attachments

Specify the folder name to upload files from with the -b option. The value to write in the attachment field of the CSV file is a relative path from the specified folder. Prepare a CSV file with data such as:

1
2


"Name","Department","Photo"
"Mason Miller","Sales","Mason_Miller.png"

To upload files from myfiles folder, use the following command:

1

> cli-kintone.exe --import -a 999 -d example.kintone.com -u Krispy -b myfiles -f sample.csv

Uploading Multiple Files

If one attachment field will have multiple uploads, separate the file names with new lines (Ex: ALT + Enter inside cells for Microsoft Excel).

1
2
3


"Name","Department","Photo"
"Mason Miller","Sales","Mason_Miller.png
Mason_Miller2.png"

Delete attachments

To delete attachments, leave the attachment field value blank in the CSV file. When deleting specific files, leave only the file names to keep.

Following is a sample CSV file that deletes all of Clark’s photos, and deletes all but one of Miller's photos.

1
2
3


"Name","Department","Photo"
"Adam Clark","Planning",""
"Mason Miller","Sales","Mason_Miller2.png"

Limitations

The limit of each file size for file uploads is 10MB.
The following fields cannot be exported:
- Status
- Assignee
- Category
- Related records
- Field group (Fields within the Field group can be exported)
- Blank space
- Label
- Border
The following fields' values cannot be added or updated when imported:
- Fields copied from the Lookup field
- Calculated
- Text with the "Calculate automatically" option enabled
- Status
- Assignee
- Category
- Created by
- Created datetime
- Updated by
- Updated datetime
- Related records
- Field group (Fields within the Field group can be imported)
- Blank space
- Label
- Border

Note

This is confirmed in cli-kintone v0.14.0 and Kintone in August 2022.

Releases

The latest version of cli-kintone v0 can be found here .