環境

macOS 10.15.7

説明

cli-kintoneは、kintoneアプリのデータをファイルに入出力することができるコマンドラインツールです。

Windows、Linux、Mac OS X 版があります。
https://github.com/kintone/cli-kintone

Zipファイルを解凍後に、実行ファイルをパスの通ったディレクトリに設置します。
コマンドラインから cli-kintone を打ち込んで Usage が表示されることを確認します。

日本語解説
https://developer.cybozu.io/hc/ja/articles/202957070

英語解説
https://developer.kintone.io/hc/en-us/articles/115002614853

cli-kintoneは Go言語で書かれています。ソースから実行ファイルを生成することも出来ます。

オプション一覧

Usage

Usage:
    cli-kintone [OPTIONS]

Application Options:
    -d=           Domain name (specify the FQDN) 必須。cybozuのドメインを指定します。例)  -d sample
    -a=           App ID (default: 0) （必須）アプリのIDを指定します。例) -a 123
    -u=           User's log in name （準必須）kintoneにアクセスする際にログインパスワードを使うときに指定 例) -u user 
    -p=           User's password（準必須）kintoneにアクセスする際にログインパスワードを使うときに指定 例) -p password 
    -t=           API token（準必須）kintoneにアクセスする際にAPIトークンを使うときに指定 例) -t APIToken 
    -g=           Guest Space ID (default: 0) （任意）kintoneのゲストスペースにアクセスする場合に指定
    -o=           Output format. Specify either 'json' or 'csv' (default: csv) （任意）出力形式を指定。省略時はCSVです。
    -e=           Character encoding. Specify one of the following -> 'utf-8'(default), 'utf-16', 'utf-16be-with-signature', 'utf-16le-with-signature', 'sjis' or
                    'euc-jp' (default: utf-8)（任意）出力形式の文字コードを指定。デフォルトはUTF-8です。--import -f でファイルから読み込んでレコードを追加・編集時は読み込み用のファイルの文字コードを指定します。（例：Shift-JISコードのファイルを読み込む場合。 --import -f import.csv -e sjis）
    -U=           Basic authentication user name （任意）アクセスするkintoneドメインにBASIC認証が設定されている場合に指定。パスワードとセットで使う。
    -P=           Basic authentication password（任意）アクセスするkintoneドメインにBASIC認証が設定されている場合に指定。ユーザー名とセットで使う。
    -q=           Query string （任意）アプリに渡すクエリ文字列。SQLライクな検索絞り込みが出来ます。例) -q "limit 10"
    -c=           Fields to export (comma separated). Specify the field code name （任意）出力する際のフィールドコードをカンマ区切りで指定。省略した場合は全てのフィールドが出力されます。例) -c "$id,文字列1行"
    -f=           Input file path（任意）CSVファイル等からレコードを追加・更新する場合にファイル名を指定。例) -f ./import.csv
    -b=           Attachment file directory （任意）添付ファイルをダウンロードする場合に、ダウンロードするディレクトリを指定。ディレクトリは自動作成される。
    -D            Delete records before insert. You can specify the deleting record condition by option "-q"（任意）レコードを削除する場合に指定。-q オプションを組み合わせて、クエリで絞り込んだ特定のレコードを削除することができる。
    -l=           Position index of data in the input file (default: 1)  （任意）インポートするファイルの読み込み位置を指定することができる。
        --import  Import data from stdin. If "-f" is also specified, data is imported from the file instead（任意）指定すると標準入力からデータを読み込む。
        --export  Export kintone data to stdout（任意）指定すると標準出力にレコードを出力する。

Help Options:（任意）cli-kintoneのオプションを表示する。
    -h, --help    Show this help message

実行例

テスト環境は macOS 10.13.6

レコード取得系

APIトークンを使って最初の10行をCSVで取得する

cli-kintone -a 123 -t API-Token -d Domain -q "limit 10"

APIトークンを使って全てのレコードをCSVでバックアップする

cli-kintone -a 123 -t API-Token -d Domain > backup.csv

Mac OS X にてファイルを確認する
head backup.csv　ファイルの先頭から10行表示
tail backup.csv　ファイルの最後から10行表示

フィールドコードを指定して標準出力する

cli-kintone -a 123 -t API-Token -d Domain -c "\$id, 顧客名, 提案プラン2, オプション2"

レコードIDのみをCSVで取得する

cli-kintone -a 123 -t API-Token -d Domain -c '$id'

または、ダブルクォーテーションで囲む場合は、$をバックスラッシュでエスケイプする。
cli-kintone -a 123 -t API-Token -d Domain -c "\$id"

シェルのパイプと組み合わせて、ヘッダー行のみを取得する

cli-kintone -a 123 -t API-Token -d Domain | head -1

レコード更新系

シェルのパイプと組み合わせて、新規に追加した自動計算フィールドを更新する

自動計算フィールドを後で追加した場合、レコードの再保存を繰り返す事無く一気に更新を掛けます。

cli-kintone -a 123 -t API-Token -d Domain -c "\$id" | cli-kintone --import -a 123 -t API-Token -d Domain

ファイルを読み込んでフィールドを更新（重複禁止フィールドをキーに指定）

更新用のCSVファイル
キーにするフィールドコードにアスタリスク(*)を付けています。
ファイルの文字コードはShift-JISの場合です。

import.csv

"*顧客コード","引き合い"
"20","電話"
"19",""
"18","メルマガ"
"17",""
"16",""

cli-kintone --import -f import.csv -e sjis -a 123 -t API-Token -d sample.cybozu.com

レコード追加系

ルックアップフィールドを持つアプリにレコードを追加する

ルックアップフィールドには(2019.10.16 現在)APIトークン認証ではレコードの追加・更新ができません。この場合はパスワード認証を使います。

営業支援パックの「案件管理」にレコードを追加します。
フィールドコード顧客名がルックアップ、案件名が必須項目です。

importfile.csv

"顧客名","案件名"
"戸田ネットソリューションズ","新規案件1"
"金都運総研","新規案件2"

cli-kintone --import -a 123 -u 'userid' -p 'password' -d Domain -f ./importfile.csv
: Start from lines: 1 - 3 => SUCCESS
: DONE

データマイグレーション時の cli-kintone の使いどころ

cli-kintone を使わなくても良い場面も多い訳で、使わざるを得ない場面で利用することになります。

既存のkintoneアプリの一部のフィールドを他のアプリに移行したいが、フィールド名が全て同じの為移行したフィールドの区別が付かない。

こんな時は cli-kintone を使ってフィールドコードを指定してCSV出力した方が早いです。
フィールド名を変更しても良いですが、同じフィールド名で100個とかあったらムリだと思います。

cli-kintone -a 123 -t API-Token -d Domain -c "\$id, 顧客名, 提案プラン2, オプション2"

-c オプションに「出力する際のフィールドコードをカンマ区切りで指定」してやりましょう。

通知について

アプリにてファイル書き出し・読み込みした際は、ユーザーに通知が飛びます。
https://jp.cybozu.help/k/ja/user/notifications/notification_type.html

対して、cli-kintone 等による、API経由のファイル書き出し・読み込みは通知が飛びません。ただし、kintoneシステム管理で REST APIの通知をメールで送信にチェックしている場合は、メールにて通知がされます。
また、API操作に関しては、cybozu.com運用基盤の監査ログに書き込まれます。

備考

ルックアップの更新にAPIトークン認証が使えない理由

kintoneの APIトークンはアプリ単位の払い出しになっています。
想像ですが、ルックアップはルックアップ元とルックアップ先（更新するアプリ）の少なくとも2つのAPIトークンが必要な為と思われます。
(2019.10.16現在)

おまけ

mac のターミナルで Shift-JIS のファイルを cat する

$ cat sjis.csv
"*�ڋq�R�[�h","��������"
"20","�d�b"
"19",""
"18","�����}�K"

普通にcat すると文字化けするので、nkf で変換します。

$ nkf -v
Network Kanji Filter Version 2.1.5 (2018-12-15)
Copyright (C) 1987, FUJITSU LTD. (I.Ichikawa).
Copyright (C) 1996-2018, The nkf Project.
$ nkf --help
Usage:  nkf -[flags] [--] [in file] .. [out file for -O flag]
 j/s/e/w  Specify output encoding ISO-2022-JP, Shift_JIS, EUC-JP
          UTF options is -w[8[0],{16,32}[{B,L}[0]]]
 J/S/E/W  Specify input encoding ISO-2022-JP, Shift_JIS, EUC-JP
          UTF option is -W[8,[16,32][B,L]]
$ cat ./csv/sjis.csv | nkf -Sw
"*顧客コード","引き合い"
"20","電話"
"19",""
"18","メルマガ"

cli-kintone に渡すオプションをあらかじめ環境変数にセットする

シェルの環境変数にオプションパラメーターをセットしておきます。

$ app=100
$ echo $app
100
$ APIToken=APIトークン
$ kintoneDomain=sample.cybozu.com
cli-kintone -a ${app} -t ${APIToken} -d ${kintoneDomain} -q "limit 10"

kintoneコマンドラインツール cli-kintone を使ってkintoneクエリを理解する

環境

説明