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 で確認したものになります。
Hitoshi Hayakawa 様
解決しそうだということで良かったです。
今後ともcybozu developer networkをよろしくお願いいたします。
shu kobayashi 様
お世話になっております。cybozu developer network事務局です。
はい、kintone コマンドラインツールについてもoffsetの上限値制限の影響がございます。
kintone コマンドラインツールが受ける影響に関して、開発チームにて対応を予定しています。
以上、よろしくお願いいたします。
いつもお世話になっております。csvからデータをインポート(新規登録)しようとしています。
下記の記載
「レコード番号以外の特定のフィールドでレコードを更新するには、CSVファイルのヘッダ行にあるフィールドコードの先頭に更新キーを表すマーク"*"をつけます。」
に従ってフィールドコードの先頭に更新キーを表すマーク"*"をつけていますが、
Status: 404 Not Found
Message: 「updateKey」に指定した条件にあてはまるレコードが見つかりません。
Errors detail: (none)
というエラーが出てしまいます。
該当のCSVでは行数は1行だけで、新しいレコードをアプリに追加しようとしています。そのため、CSV内のupdatekeyは該当のアプリにはまだ存在しません。
cli-kintoneではcsvからレコードを新規登録することはできないのでしょうか？
Seki 様
ご質問いただきありがとうございます。cybozu developer network運営チームです。
更新ではなく、新規登録する場合は、更新キーを指定する必要がございません。
詳細は「ファイルからデータをインポート」の「新規にデータを登録する」をご参考ください。
こんにちわ。
コマンドラインツールを使ってkintoneからデータをGETする機能を作っています。
簡単にデータ取得の流れは、以下の通りです。
EXCELからマクロ実行→バッチ実行→cli-kintoneにて指定したkintoneアプリからデータ取得→取得データをCSVでファイル出力
取得自体は問題なく出来ています。
けれど、取得レコードを特定の文字列フィールドの値で絞り込みたいのですが、
「クエリ記法が間違っています。」とエラーになり、うまくいきません。
クエリ記法について御教授願えないでしょうか。
実行しているコマンドは以下のようなものです。
cli-kintone.exe -a 1 -d https://testtestabcabc.cybozu.com/ -u testuser -p pass -c="$id,hiduke,hinmei,user,status" -q="作成日時>=LAST_MONTH(1) and sakujo !=削除 order by hiduke asc" -e="sjis" > test.csv
フィールドコード「sakujo 」の値が「削除」でないレコードを取得したいです。
当フィールドはドロップダウンで、用意した項目は１つで「削除」、初期値は「------」です。
ドロップダウンですので、
-q="作成日時>=LAST_MONTH(1) and sakujo not in (""削除"") order by hiduke asc"
といったコマンドも試してみましたが、同様の結果でした。
よろしくお願い致します。
Yasu.Nakashima 様
お世話になっております。cybozu developer network 事務局でございます。
クエリ記法につきましては以下の記事を参考に記述ください。
https://developer.cybozu.io/hc/ja/articles/202331474#step2
ご認識の通りドロップダウンフィールドについては、
上記のリンク先にも記載の通り、=, != は使用できません。
ドロップダウン in ("値") で指定可能ですが、コマンドラインツールでは 「"」はエスケープする必要があります。
コマンドプロンプトの場合は以下の通り、「\」でのエスケープです。
ドロップダウン in (\"値\")
パワーシェルの場合は以下の通り、「\`」でのエスケープが必要になります。
ドロップダウン in (\`"値\`")
以上、よろしくお願いします。
cybozu Development team 様
御回答頂き、ありがとうございます。
基本的な知識が欠けており、申し訳ございません。
エスケープすることで問題なくレコードを絞り込んで取得する事が出来ました。
いつもお世話になっております。
コマンドラインツールを使用して、全アプリデータのバックアップ機能を作成しております。
添付ファイルのエクスポートで、ファイル名に「~」が入っているファイルの出力時に、処理が止まってしまいます。
Midori Koyama 様
お世話になっております。cybozu developer network 運営でございます。
こちらの方で、windows 10, mac, 最新版 cli-kintone で動作確認したのですが、
同様の現象を確認できませんでした。
お手数ですが、cli-kintone を最新版にしていただき、再度ご確認ください。
現象が続く場合は、ご使用環境（OS, コマンドラインツール名）を共有いただけないでしょうか。
以上、お手数ですがよろしくお願いいたします。
cybozu Development team 様
ご回答いただきありがとうございます。
再度確認した結果、「~」が原因ではなく「<>」が問題であることがわかりました。大変失礼いたしました。
原因の添付ファイルのファイル名は帳票プラグインで自動生成しているため、
プラグインの開発元に問い合わせて対応いたします。
この度は大変お手数おかけいたしました。
Midori Koyama 様
ご連絡ありがとうございます。
承知いたしました。
今後とも cybozu developer network をよろしくお願いいたします。
Powershellからコマンドラインツールを使って添付ファイルをダウンロードしようとしているのですが、
そうしてもクエリの記述がうまくいきません。
-q 'ステータス = "申請中 （決裁待）"' や
-q '"ステータス = "申請中 （決裁待）""' など
複数ためしましたがどうしても記法が間違っていますとなります。
どのように記載すればいいのでしょうか？
江口 和志 様
お世話になっております。cybozu developer network 運営事務局でございます。
こちらのコメント欄は記事内容のフィードバック目的となっており、
記事とは直接関係がない、または技術的なご質問はcybozu developer コミュニティをご活用ください。
有志により回答が得られる場所となります。
よろしくお願いいたします。
cybozu Development team 様
いつもお世話になっております。
制限事項の「セキュアアクセス環境には対応していません」の箇所について質問です。
もう少し詳細にお聞きしたいのですが、セキュアアクセス環境には対応していませんとは具体的にどのようなシチュエーションなのでしょうか。
例えば10アカウント保有していて、そのうち5つのアカウントのみセキュアアクセスを設定していた場合、
セキュアアクセスの証明書を入れたPCでは使えないということでしょうか？あるいはセキュアアクセスを導入したドメインでは全く使えないという
ことでしょうか。教えてください。
kuma 様
お世話になっております。cybozu developer network 運営事務局でございます。
セキュアアクセスを設定したドメインにて、kintoneへのアクセスにクライアント証明書が必要な状況下ではご利用いただけません。
例えば、セキュアアクセスを設定した環境にてIPアドレス制限で社内IPアドレスのみ許可としている場合、
社内での利用：利用可
社外での利用：利用不可
となります。
よろしくお願いいたします。
cybozu developer network運営チーム
お疲れ様です。
1行目が「フィールド名」ではなく「フィールドコード」が書き出されてしまいます。
（そのため、出力したCSVを再度kintoneに取込む際にフィールドの対応付けが自動的に行われません）
「フィールド名」を出力するオプションは無いのでしょうか。
よろしくお願いいたします。
Huan Wang 様
フィールド名を出力するオプションはありません。
出力したCSVを利用してkintoneにレコード登録する方法は以下の記事に詳細がありますので、よろしければご参考ください。
https://developer.cybozu.io/hc/ja/articles/115000717706
コマンドラインツールでファイルからインポートする際に、ある項目をキーとしてレコードが「存在していたら更新」「無ければ新規追加」ということはできますでしょうか。
標準の機能ですと、ファイルから読み込む のメニューから「一括更新のキー」を指定・・・の機能と同じことがしたいです。
Okamoto 様
ご質問いただきましたアップサート機能ですが、 cli-kintone には搭載されておりません。
よろしくお願いいたします。
cybozu Development team様
回答ありがとうございます。承知しました。
コマンドラインツールを使ってkintoneからCSV形式でエクスポートしたいのですが、フィールドが意図しない並び順となりエクスポートされてしまいます。
フィールドにテーブルは使用していません。また、-cオプションは使用せず、すべてのフィールドを書き出したいです。
並び順には規則性がなく、またコマンドラインツールを実行するたびに並び順が変化します。
想定される原因についてご教示いただけますと幸いです。
kwsht 様
遅くなりましたが、調査結果を回答いたします。
cli-kintone でCSV出力される列の順番が実行する度に異なるのは、不具合ではなく、Go言語の仕様に起因するものです。
回避策として、エクスポートするフィールドを指定するを参照して -c オプションで列を固定できます。
ご不便をおかけしますがよろしくお願いいたします。
cybozu Development team様
ご回答ありがとうございます。承知いたしました。
追加で申し訳ございません。-c オプションで指定可能なフィールド数に制限値はありますでしょうか。
（50個程度のフィールド数定義を想定しています。本問い合わせと併せて、実機確認をいたします）
kwsht 様
お世話になっております。
cybozu developer network 運営事務局でございます。
ご質問いただきましたフィールド数の上限値ですが、1000フィールドになります。
(※ レコード取得APIの制限により)
よろしくお願いいたします。
cybozu Development team様
ご回答ありがとうございます。大変参考になりました。改めまして御礼申し上げます。
いつもお世話になっております。
コマンドラインツールを使ってcsv書き出しを行ったのですが、エラーになります。
現象：
プロキシ認証が必要な環境でHTTPS_PROXY環境変数を設定した後、cli-kintoneコマンドを実行したところ、「411 Length Required」が発生しました。
コマンド：
C:\xxxxxx>set HTTPS_PROXY=https://[ユーザー名]:[パスワード]@[ホスト名]:[ポート番号]
C:\xxxxxx>scli-kintone.exe -a アプリID -d ドメイン -u ログイン名 -p パスワード -e sjis -c "$id,Spec_No" > リダイレクトするファイル名
（"Spec_No"はルックアップフィールドのフィールドコードです）
結果：
YYYY/MM/DD hh:mm:ss HTTP error: 411 Length Required
弊社ではPutのアクセス制限をしているのですが、コマンドラインツールはPutを使用しておりますか？
どのような処理が行われているかを知りたいです。
また、もし、「411 Length Required」が起きた際の解決策があればご教示いただけますと幸いです。
よろしくお願いいたします。
Nishimoto 様
お世話になります。 cybozu developer network 運営でございます。
411 Length Required のエラーですが、 cli-kintone が出力するエラーではなく、
送信されたリクエストにContent-Lengthヘッダが含まれていない場合に、返されるステータスコードです。
プロキシサーバーの設定有無によってエラーが変化する場合、
cli-kintoneの実行マシンから、インターネットに出るまでの通信経路（プロキシサーバーなど）を調査する必要があると思います。
> 弊社ではPutのアクセス制限をしているのですが、コマンドラインツールはPutを使用しておりますか？
export コマンドの場合は PUT を使用しておりません。
以上、ご確認お願いいたします。
cybozu Development team様
ご回答ありがとうございます。頂きました情報をもとに確認を行ってみます。
ありがとうございました。
お世話になっております。
cli-kintone.exe を利用して定期的にデータを抽出していますが、下記のようなメッセージが表示されます。
「このアプリ（id: 686）で、 2021-02-01 7:46 にパフォーマンスに影響を与える処理が検知されました。レコード一括取得APIで offset に上限（10,000）を超える値が指定されて実行されました。詳細は、offset の制限値を考慮したレコード一括取得の案内を参照してください。」
offset の制限値を考慮したレコード一括取得の案内
を参照しましたが、cli-kintone.exe の利用においての記事は見つけられませんでした。
つきましては以下ご教示願えないでしょうか。
①cli-kintone.exeを利用における上記警告への対処方法
②上記警告がでている状態での具体的な影響（今のところ実害は出ていない認識）
よろしくお願いいたします。
木村政志 様
お世話になります。 cybozu developer network 運営でございます。
> ①cli-kintone.exeを利用における上記警告への対処方法
下記を満たすことでカーソルAPIが実行され警告が表示されなくなります。
- Version 0.10.2以上にcli-kintoneをアップデートする
更新履歴はこちら
- -q オプションを指定した際、クエリに「limit」または「offset」が含まれないようにする
その他ツールなどの影響に関してはこちらをご覧ください。
> ②上記警告がでている状態での具体的な影響（今のところ実害は出ていない認識）
サーバーに非常に高い負荷がかかる恐れがあり、パフォーマンスの低下が考えられます。kintoneの動作速度が低下するなど影響を及ぼす場合があります。
kintone API レコード一括取得APIのoffsetの上限値制限について（2020/4/15更新）
以上、ご確認をお願いいたします。