Command Line Tool Basics

Introduction

This article introduces the basic usages 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 this article for steps on preparing cli-kintone for your local environment.

Display cli-kintone options

If you run cli-kintone without any arguments, the available cli-kintone options will be listed.

 

Options

Description

Example

-d

The domain name.
Specify the FQDN of the kintone environment, such as "example.kintone.com".
This option is required.

-d sample.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://sample.kintone.com/k/27/
This option is required.

-a 27

-u

The Log in name of the kintone user to authenticate with.
Either the API token or the Log in name is required.

-u john-doe@kintone.com

-p

The Log in password for the kintone user.

-p password

-t

The API token of the App.
Either the API token or the Log in 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://sample.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 log in name.
Refer to the help article for more information on Basic Authentication.
Required, if the Basic Authentication settings have been set up for the kintone environment.

-U basicusername

-P

The Basic authentication password.

-P basicuserpassword

-q

The query for the API call.
Refer to this page 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

-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. If you wish to cancel a process while it's running, press CTRL+C.

Authenticate

Authenticate via a Username and Password

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

You will be prompted to enter a password.

Authenticate via an API Token

Use the -t option to authenticate via an API Token. Refer to this article on how to generate an API token for your kintone App. Make sure to grant the appropriate permissions to the API token.
For authenticating with an API Token of "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 "sample.kintone.com" and App ID of 999:

The result will be exported in CSV format:

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

Export to a CSV file with character encoding

By default, the character encoding is UTF-8.
Use the -e option to specify a different character encoding.
Specify the file to export to by noting the > symbol followed by the file name, such as "> myfilename.csv".
For exporting csv data to a file named "sample.csv" with UTF-16 encoding:

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

The result will be exported as below:

Export data with filter conditions and sort order

The -q option specifies the filter and sort of the exported data. Refer to this page on how to write query conditions.
For exporting records where the date field with field code "Hired_date" is before April 27th 2017:

The result will be exported as below:

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:

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 looks like the below:

US_01.PNG

Downloading 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 filed code of "pic" into the folder "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}".
downloadlist.PNG


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

Import data

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

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

The resulting data will be displayed on the console:

Add Data after Deleting Existing Data

If you specify the -D option, all existing records are deleted before adding 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.

This will be used to update as follows:

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:

This will be used to update as follows:

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. Use a carriage return (e.g. ALT+Enter inside cells for Microsoft Excel) to specify multiple attachment files.

For uploading files from the "myfiles" folder:

Was this article helpful?
0 out of 0 found this helpful
Comments
Please sign in to leave a comment.