kintone コマンドラインツール（cli-kintone）
（著者：サイボウズ KADOYA Ryo）
Index
kintone コマンドラインツールとは
kintone コマンドラインツールは、コマンドライン上からかんたんに kintone にデータのインポートやエクスポートができるツールです。
コマンドラインツールを使うと、kintone の画面から Excel/CSV をインポートしてレコードを一括登録・更新する機能でできない、次の操作も行うことができます。
- 一括でレコードの添付ファイルをダウンロードする
- 一括で添付ファイルをレコードに添付する
また、シェルスクリプトと組み合わせると、kintone のデータのインポートやエクスポートを定期実行できます。
コマンドラインツールのダウンロード
kintoneのコマンドラインツールはこちらからダウンロードできます。
Windows/MacOSX/Linux向けの実行ファイルが用意されています。
ダウンロードしたら任意のフォルダに解凍してください。ここではWindowsでの利用を想定します。
Releases kintone/cli-kintone (Github)
オプションの一覧を確認する
引数をなにも指定せずに実行すると、利用可能なオプションが表示されます
| オプション | 説明 |
| --export | kintoneからデータをエクスポートする場合に指定します。 データは標準出力にエクスポート（コンソールに表示）されます。 |
| --import | kintoneにデータをインポートする場合に指定します。 データは標準入力からインポートされます。 -f オプションも指定されている場合、対象ファイルからデータがインポートされます。 |
| -d | ドメイン名（必須）cybozu.comは省略可能です。 FQDNを指定することで、cybozu.com 以外のドメイン(kintone.com, cybozu.cn) を利用することも出来ます。 |
| -a | アプリID（必須） |
| -u | ログイン名（APIトークンかログイン名のいずれかが必須） |
| -p | パスワード |
| -t | APIトークン（APIトークンかログイン名のいずれかが必須） |
| -g | ゲストスペース内アプリの場合、ゲストスペースのIDを指定します。 |
| -o | 出力形式。'json'もしくは'csv'が指定できます。デフォルトは'csv'です。 |
| -e | インポート・エクスポートするファイルのエンコード方式。 デフォルトは UTF-8 です。 対応するエンコード方式とオプションに指定できる値は、それぞれ次のとおりです。
|
| -U | BASIC認証ユーザー名 |
| -P | BASIC認証パスワード |
| -q | 条件式。条件式の書き方はこちらを参照してください。 オプション指定時、かつ、「Limit」または「offset」を含まないとき、カーソル APIを利用して処理が実行されます。 |
| -c | エクスポートするフィールドコードをカンマ区切りで指定できます。 |
| -f | データインポート時、インポートするファイル名を指定します。 |
| -b | 添付ファイルのダウンロード先、アップロード元ディレクトリを指定します。 |
| -l | データをファイルからインポートする場合に、インポート開始行を指定します。 このオプションを指定すると、データのインポートは指定した行から開始されます。 |
| -D | インポート時にこのオプションを指定すると、既存のレコードをすべて削除してからデータをインポートします。 |
ユーザー名/パスワードでkintoneのデータを表示する
ドメイン名をsample.cybozu.com、アプリIDが999の場合の例
bozumanユーザーのパスワードを入力すると、CSV形式ですべてのフィールドのデータがエクスポートされます。
JSON形式で表示するには、-o jsonを指定します。途中で中断する場合は、CTRL+Cを押してください。
結果は以下のようになります
APIトークンを利用する
APIトークンを利用すると、パスワードを入力しなくてもデータをインポート・エクスポートすることができます。
APIトークンは、アプリの設定 > APIトークンから取得できます。実行する操作にあわせて、APIトークンに適切な権限を設定してください。
※ 追加・更新の対象にルックアップフィールドが含まれている場合、APIトークンを利用できません。
ユーザー名/パスワードを利用してください。
Shift-JISでエクスポートする
kintoneではデフォルトでUTF-8で文字列データがエクスポートされます。
-eオプションを使うことで、エクスポートする文字エンコーディングを指定することができます。
CSVファイルに実行結果をリダイレクトする
次のように「>」を使用することで、cli-kintoneの実行結果をCSVファイルにリダイレクトできます。
エクスポートするフィールドを指定する
-cオプションを使うことで、エクスポートするフィールドを指定できます。
- テーブルの値を出力する場合は、テーブル自体のフィールドコードを指定してください（テーブル内のフィールドコードを指定して出力はできません）。
絞り込み条件と並び順を指定する
-qオプションを使うことで、絞り込み条件と並び順を指定できます。
条件式の書き方はこちらを参照してください。
ファイルからデータをインポートする
既存のデータを更新する
既存のデータを更新するには、CSVファイルに$idカラムを用意します。
加藤さんの所属を企画部に、山田さんの所属を人事部に変更するCSVファイルの例
顧客コードでレコードを更新するCSVファイルの例
新規にデータを登録する
CSVファイルに$idカラムが存在しない場合や、$idカラムの値が空文字列の場合、新規にレコードが登録されます。
ここまでの結果は以下のようになります。
既存のデータを削除して登録する
-Dオプションを指定すると、既存のレコードをすべて削除してからデータを追加します。
テーブルの書き出し、読み込み
書き出し
テーブル付きのレコードを書き出す場合、1レコードの内容が複数行に分けて書き出され、CSVデータのエクスポート結果は以下のようになります。
この例では異動年月日と異動部署がテーブルになっています。
書き出したCSVの1行目には１列目に"*"マークが出力され、その後フィールドコード名が並びます。
2行目以降で"*"マークがついていない行は、テーブル内の２行目以降のデータになります。
上記のCSVデータの場合、5レコードがエクスポートされています。
$idが5の『異動年月日』と『異動部署』を含むテーブル内に2行分のデータが入っているため、CSVでも2行分のデータがエクスポートされています。
読み込み
読み込みも同様に、2行目以降で"*"マークがついていない行は、テーブル内の２行目以降のデータとして扱われます。
先頭列に"*"がついていない行の、テーブルの行以外の値は無視されます。
添付ファイルのダウンロード、アップロード
ダウンロード
-bオプションに、ダウンロード先のフォルダ名を指定します。フォルダが存在しない場合は、自動的に作成されます。
ここでは「写真」フィールドのフィールドタイプが添付ファイルに設定されているものとします。
-bオプションを指定したとき、添付ファイルフィールドの値はダウンロードされたファイルのダウンロードフォルダからの相対パスとなります。
添付ファイルは、downloadフォルダ以下の<添付ファイルのフィールドコード>-<$id>フォルダにそれぞれ保存されます。
また、-cオプションを指定したとき、エクスポートするフィールドに"$id"または"レコード番号"が含まれていない場合には、
添付ファイルは、downloadフォルダ以下の<添付ファイルのフィールドコード>-<Index(※)>フォルダにそれぞれ保存されます。
※ Index は0から始まり、取得対象のレコード数に合わせて増加します。
例）取得対象のレコードが3件の場合
<添付ファイルのフィールドコード>-0
<添付ファイルのフィールドコード>-1
<添付ファイルのフィールドコード>-2
アップロード
ダウンロードと同様に、-bオプションでアップロードするフォルダを指定します。
CSVファイルに記述する値はアップロードフォルダからの相対パスとなります。
複数の添付ファイルを指定するときは、CR文字（Microsoft Excelの場合はALT+Enterキーで入力）でファイルを区切ります。
レコードの添付ファイルを削除するときは、削除したい添付ファイルフィールドの値を空白にします。
複数のファイルを添付している場合で一部の添付ファイルを削除したい場合は、添付ファイルフィールドの値を残したいファイルのファイル名のみにします。
この例では、$idが5のレコードで「写真」フィールド（添付ファイルフィールド）の添付ファイルが削除されます。
制限事項
- クライアント証明書を利用したセキュアアクセス環境での操作には対応していません。
IPアドレス制限設定環境下では、アクセスが許可されたIPアドレスからツールを実行する必要があります。 - アップロードできる添付ファイルのサイズの上限は、1ファイルあたり10MBです。
- 次のフィールドはエクスポートできません。
- ステータス
- 作業者
- カテゴリー
- 関連レコード
- グループ
グループフィールド内のフィールドはエクスポートできます。 - フォームを装飾するフィールド（スペース、ラベル、罫線）
- 次のフィールドにインポートしても値は登録・更新されません。
- ルックアップ元からコピーされるフィールド
- 計算
- 自動計算が設定されている文字列（1行）フィールド
- ステータス
- 作業者
- カテゴリー
- 作成者
- 作成日時
- 更新者
- 更新日時
- 関連レコード
- グループ
グループフィールド内のフィールドはインポートできます。 - フォームを装飾するフィールド（スペース、ラベル、罫線）
おわりに
コマンドラインツールはREST APIを使用するため、スタンダードライセンスが必要です。
大量のデータ操作はkintoneに負荷がかかり、パフォーマンスに影響が出ることがありますのでご注意ください。
関連Tips
- 定期実行でデータの同期を実現するスマートな方法
- はじめようkintoneコマンドラインツールシリーズ（数回に分けて詳しくkintoneコマンドラインツールの使い方を解説しています）
このTipsは、cli-kintone Ver 0.14.0 と2022年8月版 kintone で確認したものになります。
既存システムとkintoneへのデータ移行や、同期のため、APIプログラムを個別開発していましたが、
これで楽になりますね。その他ERPパッケージシステムとのCSV連携にも利用できますね。
こんにちは
キントーンコマンドツールを利用させて頂いています。
Releases kintone/kintone-ci (Github）
Windows版で公開されているのが64ビット版のみなのですが、32ビット環境で利用する必要がでてきたので、ソースとビルドの手順が公開されているので自分で32ビット版を作成しようと試みました。
しかし、
https://github.com/kintone/kintone-ciの「How to Build」の手順でbuild(go build)を実行すると。
「import code.google.com/p/go.text/encoding: c:\go\src\kintone-ci\main.go:4:2: package could not be found loccally」
のエラーが発生してbuildが失敗してしまいます。
ビルドの正しい手順もしくは、Windows32ビット版のexeがあれば教えて頂けませんでしょうか。
Go言語、Git、Mercurialをそれぞれインストールし、環境設定をして手順に従ってビルドすれば、32ビット版のexeが出来ましたよ。
色々とアドバイス頂き、Go言語を再インストールして再度ビルドした所、32ビット版作成できました。
ありがとうございました。
64bit版同様に、32bit版のソースとビルドの手順も公開して頂けないでしょうか。
よろしくお願いいたします。
macosx版のv.0.1とv.0.2を使用してCSV出力をしてみましたが、
1行目が「フィールド名」ではなく「フィールドコード」が書き出されてしまいます。
（そのため、出力したCSVを再度kintoneに取込む際にフィールドの対応付けが自動的に行われません）
「フィールド名」を出力するオプションは無いのでしょうか。
コマンドラインツールを利用し、サブテーブルのフィールドデータを、
エクスポート、および、インポートすることは可能でしょうか？
かんさん
お世話になっております。cybozu.com developer network事務局です。
下記をご参考いただければと思います。
http://qiita.com/ushiron/items/f7f66632710b9b0834c5
カテゴリー項目が出力されなくて困っております。カラム名で指定しても出てこないので仕様なのかな？とおもっているのですが、なにか手段は有りますでしょうか？？
PDF等のファイルを一括で登録したいのですが、コマンドラインツールでも可能でしょうか。
データの取込は問題なく出来たので、後はそのデータに紐づく各種書類ファイルを登録したいと考えております。
いつも良質な記事ありがとうございます。
2点ほど確認・教えて頂きたいのですが、
・文字列内にカンマが含まれる場合には、ダブルコーテーションで文字列を囲えば正しく文字列として判断される？
・文字列内にダブルコーテーションが含まれる場合には、ダブルコーテーションで文字列を囲えば正しく文字列として判断される？
という認識で宜しかったでしょうか？
教えて頂ければ幸いです。
宜しくお願い致します。
コマンドラインからRESTを使って添付ファイルをUPする方法を検討していましたが、
コマンドラインはShift-JIS、kintoneはutf-8ということでファイルのタイトルが文字化けしていました。
本ツールを使うことで解決しました。助かります！
コマンドラインから、サブテーブルとルックアップフィールドを含むCSVを取込もうとしたら、
「APIトークンを使用する場合、ルックアップフィールドを編集できません。」のエラーがでました。
たしかにルックアップを使用しており、そこには、紐付くマスタのIDが格納されております。
ルックアップのもととなるマスタに対して編集するわけではなく、単純にIDセットしたいだけなのですが、
どのように回避したらよいでしょうか？
hiroyukijさん
ご質問いただきありがとうございます。cybozu developer network運営チームです。以下回答させていただきます。
APIトークンはそのアプリ固有の認証コードになります。
ルックアップをする場合は、他のアプリから参照することになるので、APIトークンでは参照先アプリの認証を突破できません。
そのため記載いただいたエラーが出ているものと思われます。
APIトークンではなく、ユーザー認証を使った方法に変更いただくと処理が通るようになります。
ご確認よろしくお願いします。また何か追加で疑問点などありましたらコメントください。
cybozu.com developer network事務局さん
ユーザー認証で試してみたらいけました！大変助かりました。ありがとうございました。
コマンドラインから、プロセス管理されているステータスを更新する方法はどうすればよいのでしょう。
[$id]と[ステータス]の項目をもつCSVを取込もうとしています。
-c $id,処理状況 や -c $id,ステータス では拾ってくれませんね・・・。 私も このステータス項目の一覧をだしたいです
hiryukijさん、GP-KIYOさん
ご質問いただきありがとうございます。cybozu developer network運営チームです。
コマンドラインツール（cli-kintone）ではJSON形式でステータス情報の取得はできますが、ステータスの更新はできません。
ステータス更新につきましては、レコードのステータスの更新APIをお使いいただいて処理を記述することになります。
https://cybozudev.zendesk.com/hc/ja/articles/204791550
ご確認よろしくお願いします。
他にも疑問点がありましたらお知らせください。
cybozu.com developer network事務局さん
なるほど了解しました。残念です。。今後検討して頂けるとありがたいです。
こんにちは。1つ質問です。
cli-kintone でダウンロードできるデータの最大件数（制約）などはありますか？
岩崎充宏さん
ご質問いただきありがとうございます。cybozu developer network運営チームです。
コマンドラインツールでは、入っているレコードデータを全件取得するようになっています。
取得する上限を決めたい際は、「query」パラメータにlimitを指定してください。指定の仕方は以下をご参照ください。
https://cybozudev.zendesk.com/hc/ja/articles/202331474#step2
因みに途中で処理を中断させたい場合は、CTRL+Cを押して停止することが可能です。
ご確認よろしくお願いします。また何か疑問等ありましたらお気軽にご質問ください。
cybozu developer network運営チームさん
ご回答ありがとうございます。
もう1点教えていただけますか？
cli-kintoneは、内部的にREST APIを呼んでいるという記事を見たことがある気がしています。
その場合、1日のリクエストの制限に引っかかったりして、レコード全件が取得できない(途中でエラーとなる）
といったことはありますか？
CLIで ステータス="ABC" のレコードを抽出する事はできませんか？
-b で添付ファイルを出力するのに、 -qオプションを 指定してレコードを指定した添付ファイルを取得しようとしているのですが、-b -q "$id=1"とすると、 -qというフォルダを作成して 全ファイルを出力してしまいます。
逆に -q "$id=1" -b とすると実行できません。
どのように実行したら条件に応じたファイル出力ができますでしょうか
岩崎充宏さん
ご質問いただきありがとうございます。cybozu developer network運営チームです。
岩崎さんのおっしゃる通り、内部的にはREST APIを呼び出しています。
現時点では１アプリあたり１日10000リクエストを上限としていますが、
エラー処理やリクエストを止めるなどの処理をサイボウズ側では行っておりません。
※超過した日の翌日9：00頃に「サイボウズドットコム ストア」の
管理者メールアドレス宛に警告メールが送信されるようになっています。
http://faq.cybozu.info/alphascope/cybozu/web/kintone/Detail.aspx?id=1874&isCrawler=1
リクエスト数のカウント方法につきましては以下をご参照ください。
コマンドラインツールのソース内では一度のAPIコールで取得する上限値を以下の通り設定しています。
実際にはこれをループさせて全件取得するようになっています。
https://github.com/kintone/cli-kintone/blob/master/main.go
const IMPORT_ROW_LIMIT = 100
const EXPORT_ROW_LIMIT = 500
ご確認よろしくお願いします。
GP-KIYOさん
ご質問いただきありがとうございます。cybozu developer network運営チームです。
●一つ目のご質問
[絞り込み条件と並び順を指定する]の項目にある通り記載していただくとステータスがABCのレコードを抽出することが可能です。
https://cybozudev.zendesk.com/hc/ja/articles/202957070
具体的には以下のような記述になります。
-q "ステータス=\"申請中\""
●二つ目のご質問
ダウンロード先のファイル名を指定していただくと上手くいくかと思います。
-b download -q "$id=1"
ご確認よろしくお願いします。
お世話になっております。
証明書が入っているドメインに対してコマンドラインツールは利用可能でしょうか？
コマンドラインツールを使用しようとしてエラーになっていましたが、環境変数HTTPS_PROXYを設定することで使用できました。
知っている人には当たり前だと思いますが、情報を展開しておきます。
（状況）
社内ネットワークの制限で、ポート443による通信が抑止される環境で使用しています。
当初、以下のようなメッセージが出てエラーになりました。
2017/02/16 12:00:00 Get https://×××.cybozu.com/k/v1/form.json: dial tcp XXX.XX
X.XXX.XXX:443: connectex: No connection could be made because the target machine
actively refused it.
メッセージより、このツールはポート443を直接指定して通信しようとしていると判断しました。
（前提）
このツールはGo言語で作られている。
Goはデフォルトでは環境変数HTTP_PROXYかHTTPS_PROXYを参照する。
試行していたPCは環境変数のHTTP_PROXYもHTTPS_PROXYも設定していなかった。
社内ネットワークにプロキシサーバーは存在する。
（対応）
システムで環境変数を設定するか、ツール実行前にset文で環境変数を設定する。
set文の例：set HTTPS_PROXY=https://xxx.xxx.xxx.xxx:pppp
（xxx.xxx.xxx.xxxは社内ネットワークのプロキシサーバーアドレス。ppppはプロキシサーバのポート番号）
ootaさん
>証明書が入っているドメインに対してコマンドラインツールは利用可能でしょうか？
セキュアアクセスが有効になった状態でも利用可能かとおもいます。
当方に確認環境がないため動作を見れていませんが、ドメイン名設定の「-d」オプションで ".s" 付きURLを設定してみてお試しください。
例：">cli-kintone.exe -a 999 -d sample.s.cybozu.com -u bozuman -c "$id,氏名,写真" -b download
■参考
コマンドラインのオプションについて：https://cybozudev.zendesk.com/hc/ja/articles/115000297083
セキュアアクセス時のURLの違いについて：https://help.cybozu.com/ja/general/admin/secureaccess.html
コマンドラインツールを使ってkintoneからデータをGETしようとしていますが、
セキュアアクセスを設定した場合失敗してしまいます。
上のコメントの通りには試してみましたが…
試した内容は以下の通りです。
・セキュアアクセスを利用しない場合
実行コマンド：cli-kintone -a 1 -d [ドメイン] -u [ユーザ]
→GETできます。
・セキュアアクセスを利用する
（IPアドレス制限をすべて"拒否"としクライアント証明書で認証する使い方にした場合）
実行コマンド：cli-kintone -a 1 -d [ドメイン] -u [ユーザ]
→失敗「HTTP error: 403 Forbidden」
実行コマンド：cli-kintone -a 1 -d [ドメイン].s.cybozu.com -u [ユーザ]
→失敗「HTTP error: 400 Bad Request」
テストしているPCから、ブラウザでクライアント証明書で認証してkintoneの利用は出来る状態です。
何か解決方法はあるでしょうか？