Overview

This article introduces how to download and upload attachments from Kintone records using cli-kintone .

This tutorial uses Kintone Apps that are available in the Kintone Marketplace .

Initial Setup

This section introduces the required Kintone Apps and settings.

Create a Sample App

1. First, create a new Kintone App. From the Kintone Marketplace choose Project Management Pack.

   

2. Add a few records that include attachments inside.

   

Generate an API Token

Follow the steps in the Generating API Tokens article to generate an API token for both apps. Make sure to check the View Records, Add Records, and Edit Records* option, and take note of the API token, as it is needed in the later steps.

Download Attachments

To download attachment files from records, use the record export command. In addition, 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

cli-kintone.exe record export --base-url KINTONE_URL --app APP_ID ^
  --api-token API_TOKEN --attachments-dir DIRECTORY_PATH

• --base-url: The Kintone subdomain name (ex: https://example.kintone.com )
• --app: The App ID to retrieve attachments from
• --api-token: API token copied from Initial Setup
• --attachments-dir: The directory to which the attachment will be downloaded to

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.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# The file will be output to the "downloads" 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 125 ^
  --api-token CNk3wfOufWtASDc6miMBTEa2SEm3ZokIcJPOSKJD --attachments-dir ./downloads

# Resulting Output
"Record_number","project_name","status","start_date","end_date","project_manager","project_team_members","project_description","attachments","Author","Created_datetime","Last_user","Updated_datetime"
"1","Advertising and Promotion","Not started",,,"jessica",,"<div><br /></div>","attachments-1/kdp_01.png","jessica@kintone.com","2024-02-16T05:14:00Z","jessica@kintone.com","2024-02-16T05:14:00Z"
"2","Competition Analysis","Not started",,,"jessica",,"<div><br /></div>","attachments-1/kdp_02.png","jessica@kintone.com","2024-02-16T05:14:00Z","jessica@kintone.com","2024-02-16T05:14:00Z"
"3","Youtube Content Creation",,,,"albert",,"<div><br /></div>","attachments-3/kdp_03.png
attachments-3/kdp_04.png","albert@kintone.com","2024-02-19T07:28:00Z","albert@kintone.com","2024-02-19T07:28:00Z"

Example Directory Structure

1
2
3
4
5
6
7
8
9

works # location of the cli-kintone executable
└─── downloads
    └── attachments-1
        └── kdp_01.png
    └── attachments-2
        └── kdp_02.png
    └── attachments-3
        ├── kdp_03.png
        └── kdp_04.png

Download Attachments from Table Data

When downloading attachments from Table data, a directory with the name structure of FieldCode-RecordNumber-RowNumber will be created, with the files included inside. The row number starts with 0.

Example Directory Structure

1
2
3
4
5
6

works # location of the cli-kintone executable
└─── downloads
    └── table-1-0 # directory with the name structure of "FieldCode-RecordNumber-RowNumber"
        └── kdp_01.png
    └── table-1-1
        └── kdp_02.png

Upload Attachments to New Records

To upload and attach files, use the record import command. In addition, 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 CSV file

1
2
3

"project_name","attachments"
"Marketing Campaign","kdp_01.png
kdp_02.png"

Example Directory Structure

1
2
3
4

works # Directory containing cli-kintone.exe
└── attachments
  ├── kdp_01.png
  └── kdp_02.png

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

Example

1
2
3
4
5
6
7

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

[2024-02-19T07:33:37.548Z] INFO: Starting to import records...
[2024-02-19T07:33:39.635Z] INFO: Imported 1 records successfully

If successful, the record will be added with the files displayed in the Attachments field.

Update Attachments of Existing Records

To update attachments, use the record import command with the --attachments-dir option again. In addition, specify the records to update with the --update-key option.

• --update-key: The field code of the field used as the key for updating.

For more information about updating records, refer to the Import Data with the Command Line Tool article.

In this example, the attachments uploaded in the previous section are updated. Replace the "kdp_02.png" value in the CSV file with the "kdp_03.png" value and keep the "kdp_01.png" value. If not, the file will be deleted.

Example CSV file

1
2
3

"Record_number","project_name","attachments"
"4","Marketing Campaign","kdp_01.png
kdp_03.png"

Example Directory Structure

1
2
3
4
5

works # Directory containing cli-kintone.exe
└── attachments
  ├── kdp_01.png
  ├── kdp_02.png
  └── kdp_03.png

When the command is run, the total number of updated records will be output in the command prompt.

Example

1
2
3
4
5
6
7
8

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

[2024-02-19T07:37:05.881Z] INFO: Preparing to import records...
[2024-02-19T07:37:06.812Z] INFO: Starting to import records...
[2024-02-19T07:37:09.180Z] INFO: Imported 1 records successfully

If successful, the "kdp_02.png" file will be deleted from the Attachments field. The "kdp_01.png" and "kdp_03.png" files will be uploaded instead.

Delete Attachments

To delete attachments, use the record import command with the --attachments-dir option again and leave the attachment field value blank in the CSV file. In addition, specify the records to update with the --update-key option.

Example CSV

1
2

"Record_number","project_name","attachments"
"1","Advertising and Promotion",""

Specify --attachments-dir even if all attachments will be deleted. When the command is run, the total number of added and updated records will be output in the command prompt.

Example

1
2
3
4
5
6
7
8

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

[2024-02-16T09:12:12.424Z] INFO: Preparing to import records...
[2024-02-16T09:12:14.454Z] INFO: Starting to import records...
[2024-02-16T09:12:18.623Z] INFO: Imported 1 records successfully