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 で確認したものになります。
Seki様
ご質問いただきありがとうございます。cybozu developer network運営チームです。
IPアドレス制限をすべて"拒否"にするのは行けないと思います。
手元に確認環境がないため動作を見れていませんが、
IPアドレスを、開放または一部開放（コマンドライン実行用のIPアドレス）とした上で、ログイン名とパスワード認証でお試ししていただけますでしょうか。
cybozu Development team様
回答ありがとうございます。
という事は、そもそも REST API での連携とセキュアアクセス（クライアント証明書）が併用出来ないという事で宜しいでしょうか？
この手の分野の知識に乏しいため常識的な確認かも知れませんが、教えてください。
以上、宜しくお願い致します。
Seki様
お世話になっております。
ご質問いただきありがとうございます。cybozu developer network運営チームです。
現時点でREST APIに証明書の情報を載せる方法がないので、
REST APIを使って、証明書が入っている環境と外部サービス間でデータをやり取りすることはできません。
ご希望に添えず申し訳ございません。
cli-kintoneを使う場合、証明書が入っている環境でも、IPアドレス許可 + ログイン名とパスワードの認証でレコード取得できるかと思います。
ご確認お願い致します。
お返事が遅くなり、すみません
現状ですと、証明書が入っている場合に利用するのが難しそうですね...
検証していただき、ありがとうございます
cybozu Development team様
いつもありがとうございます。
上記にてコメントを提出させていただきましたが、自己解決致しました。
大変申し訳ございませんが、取り下げさせていただきます。
＊弊社作成のアプリの設定誤りがございました。
お世話になっております。
コマンドラインツールの構文が同じなのに環境によって出力結果が違うということはありえるのでしょうか？
実はサブテーブルつきのアプリからサブテーブルを-cオプションで指定しているのですが、私が実行して出力されたcsvのとお客様の環境で実行し出力されたcsvに差異があります。
サブテーブルは6つの項目からなり、私のほうで実行すると6つが出力されるだけなのですが、お客様の環境で実行すると6つの項目のほかにサブテーブルのフィールドコードの名称の列が出力されます。
パッと見た感じサブテーブルの行ID？
出力対象の1レコード目がサブテーブル3行だとすると10000,10001,10002
2レコード目がサブテーブル2行なら10003,10004となります。
よろしくお願いします。
デバックした結果 record['テーブル'][value][0][id]のようでした。
よろしくお願いします。
Taiki Goto様
返事が遅れまして申し訳ありません。
record['テーブル'][value][0][id]でしたら、テーブルの行IDですね。
行IDは本記事の記載通りに、普通に出力されます。
全く同じ構文でしたら、環境依存かもしれません。
こちらで試した結果、同じく行IDが出力されます。
cybozu Development team様
お世話になっております。
あれから色々試したのですがcli-kintoneのバージョンの違いのようです。
バージョン７では行IDは出力されませんでした。
Taiki Goto 様
バージョンの違いですね。失礼しました。
お世話になっております。
kintoneコマンドラインツールを使用して添付ファイルを含むレコードの取得をしようとしたところ、
コマンド上に以下のような文章が表示され、取得できませんでした。
レコード数は200件ほどです。
2017/09/26 14:57:16 Get https://×××.cybozu.com/guest/xx/k/v1/form.json: dial tcp XXX.XX
X.XXX.XXX:443: i/o timeout
問題としては何が考えられるでしょうか
鈴木 様
いつもお世話になっております。
cybozu developer networkの運営事務局です。
ご質問のエラーはkintoneで用意しているものではないので、
Webなどの情報を参考にすると、お客様環境のネットワークに依存した問題だと思われます。
(APIクライアントからcybozu.comへの接続が怪しいのではないかと思います。）
エラーメッセージからwebで検索すれば原因がわかるかと思いますので、
それらを参考にして解決していただければと思います。
よろしくお願いします。
cybozu Development team 様
回答いただき、ありがとうございます。
確認してみます。
フィールド、システム識別子ごとの利用可能な演算子と関数一覧について、
日時または日付が空（null?）の場合の条件を付けたいのですが、どのようにすれば良いでしょうか？
以下のようにやってもうまくいきません。
>cli-kintone.exe -a 999 -d sample -u bozuman -q "日付 != \"\""
Atsushi Yatabe様
ご質問の件ですが、記事のシナリオから離れているため、コミュニティでご質問をお願いできますでしょうか。
コマンドラインツールのクエリはREST APIのクエリの記述法と同様ですので、
REST APIフォーラムでご質問いただければと存じます。https://developer.cybozu.io/hc/ja/community/topics/200034355
大変助かりました！
1点だけなのですが、コマンドラインツールを利用してDATETIME型をインポートすると時間がずれます。
どのように対応すればよろしいでしょうか？ご教示くださいませ。
リクエスト値：2018/8/1 11:26:00
入力値：2018-08-01 23:26
mamoru 様
お世話になっております。cybozu developer network事務局でございます。
cli-kintoneはREST APIの仕様と同一となっており、通常、日時フィールドはUTC時間で保存されるため誤差が発生します。
https://developer.cybozu.io/hc/ja/articles/202166330
また、ご質問の件は記事と直接関係がないため、コミュニティでご質問頂きますようお願い致します。
お世話になっております。
cli-kintoneのコマンドを使って、カラム指定をしてエクスポートしたいのですが、サブテーブルの項目だけエクスポートされません。
（カラム指定しなければ、エクスポートされます。）
以下のように記載しておりますが、何か書き方が間違っているのでしょうか？
ご教授の程、よろしくお願い致します。
例）部・役職・氏名はサブテーブルです。
cli-kintone.exe -a 100 -d aaa -t トークン -c "$id,更新者,更新日時,顧客コード,会社,営業所,郵便番号,都道府県,市区町村,住所,部,役職,氏名" -q "更新日時 > \"2018-09-05T03:46:05\"" -e sjis >C:\kintone\EXP.cav
gunyakun 様
お世話になっております。cybozu developer network事務局でございます。
サブテーブルを指定する場合は、テーブル自体のフィールドコードを指定してください。
技術的な質問がある場合は、コミュニティをご活用ください。
よろしくお願い致します。
お世話になります。
コマンドラインツールのV0.9.3をダウンロードして動かしてみたところ、--export時に-e sjisを指定すると日本語のフィールドが取得できません。
-e sjisを指定しないと問題はなさそうですね。
V0.9.2では-e sjisを指定すればきっちりsjisで取得できていましたが・・。
何か仕様変更が入ったのでしょうか？
Sog 様
お世話になっております、cybozu developer network事務局でございます。
ご指摘の点につきまして、弊社環境でも同様の事象を確認しました。
本件の対応・進捗につきましては、こちらでご報告させていただきます。
ご不便をおかけして申し訳ございません。
Sog 様
お世話になっております、cybozu developer network事務局でございます。
コマンドラインツールのVersion 0.9.3について、エクスポート時にsjisで日本語のフィールドが取得できない件、
修正の対応が完了いたしました。
下記ページの「Version 0.9.4」をご利用ください。
https://github.com/kintone/cli-kintone/releases
この度はご迷惑をお掛けしまして申し訳ございません。
引き続きご活用いただけますと幸いです。
お世話になっております。
cli-kintoneのWindows64版のZIPを解凍したところ、セキュリティに引っ掛かかってしまいます。
こちらの環境のせいでしょうか？？。
TK 様
お世話になっております、cybozu developer network事務局でございます。
添付いただいた画像を拝見する限りでは、cli-kintone.exeファイルによって
お客様環境のセキュリティサービスが起動しているようです。
お客様環境や設定によって、どのような条件でセキュリティサービスが起動するのか異なるため、
対策方法はご案内できかねます。
ご期待に添えず、申し訳ございません。
cybozu Development team 様
お世話になっております。
そうですよね、すみませんお手数おかけしました！
これからもよろしくお願いします！
Version 0.9.4 を使って、いくつかのアプリのデータをダウンロードしているのですが、特定のアプリだけ何の応答も返さずに終了してしまいます（エラーも何もでません）。
プログラムは ./cli-kintone --export -d xxxxx.cybozu.com -a 12345 -u USERNAME -p PASSWORD みたいな呼び出し方をしています。わざとパスワードを変更した場合は「[CB_WA01] ユーザーのパスワード認証に失敗しました」が、アプリから閲覧権限を抜いた場合「 [CB_NO02] 権限がありません」が表示されるため、パスワードやアプリの権限の問題では無いと思います。どのような原因が考えられるでしょうか？
Hitoshi Hayakawa様
お世話になっております。
こちらでも検証いたしましたが、再現しない状況です。
恐れ入りますが、以下についてご確認いただけないでしょうか？
以前のバージョンは以下からダウンロードいただけます。
https://github.com/kintone/cli-kintone/releases
以上、よろしくお願いいたします。
1. 0.9.0/0.8 のどちらも同じ状況でした（0.8の場合、--export オプションが使えないということはありますが）。
2. アプリをコピーし、作成したアプリに対していくつか適当にデータを入力して CLI ツールを実行したところ、入力したデータが落ちてきました。原因は何が考えられるでしょうか？
→ すいません、どうも lookup フィールドの設定が誤っていたようです。CLI以前に CSV でもデータが0バイトになっているので、そのあたりの設定を直せばおそらく CLI でもダウンロードできそうです（まだ未確認）。
お騒がせしました。
cybozu developer network運営チームさん
kintone コマンドラインツールの利用にあたって、
こちらのAPI仕様変更の影響はありますでしょうか？？
https://cs.cybozu.co.jp/2019/006924.html
漠然とした質問で申し訳ございませんが、宜しくお願いいたします。