Ginue

Ginue is the CLI tool to edit settings of kintone via kintone REST API.

kintone REST APIでkintoneアプリの設定情報を編集するためのCLI版ツールです。

インストール方法

グローバルにインストールする場合

$ npm install -g ginue
 or
$ yarn global add ginue

プロジェクトごとにインストールする場合

$ npm install --save-dev ginue
 or
$ yarn add --dev ginue

使い方

Gitライクな一連のコマンドを提供します。

ginue pull : kintoneの設定情報を取得します。
ginue push : kintoneの設定情報を送信します。
ginue deploy : kintoneアプリの設定を運用環境へ反映します。
ginue reset : kintoneアプリの設定の変更をキャンセルします。
ginue erd :（実験的機能）kintoneアプリのルックアップ関係を解析してER図を作成します。

共通オプション

コマンドライン引数から指定

  -v, --version                    Output version information
  -h, --help                       Output usage information
  -d, --domain=<DOMAIN>            kintone domain name
  -u, --user=<USER>                kintone username
  -p, --password=<PASSWORD>        kintone password
  -a, --app=<APP-ID>               kintone app IDs
  -g, --guest=<GUEST-SPACE-ID>     kintone guest space ID
  -b, --basic=<USER[:PASSWORD]>    kintone Basic Authentication user and password
  -A, --appName=<APP-NAME>         Set target app name
  -l, --location=<LOCATION>        Location of settings file
  -t, --fileType=<FILE-TYPE>       Set file type 'json'(default) or 'js'
  -F, --pfxFilepath=<PFX-FILEPATH> The path to client certificate file.
  -P, --pfxPassword=<PFX-PASSWORD> The password of client certificate.

domain user password appオプションを省略した場合、標準入力を求められます。
アプリID（appオプション or 標準入力）はカンマ区切りで複数指定可能です。
ゲストスペース内のアプリ情報を取得する場合はguestオプションが必須です。
Basic認証を使用する場合はbasicオプションが必須です。パスワードを省略した場合、標準入力を求められます。
クライアント証明書を使用する場合はpfxFilepath pfxPasswordオプションが必須です。pfxPasswordを省略した場合、標準入力を求められます。
locationオプションを指定すると、kintone設定情報ファイルの保存フォルダを指定できます。（省略時はカレントディレクトリ）
fileTypeオプションにjsを指定すると、kintone設定情報ファイルを.jsonではなく.jsフォーマットで扱います。
コマンドライン引数のほか、後述する.ginuercや.netrcでもオプション指定が可能です
- username, password, basic, pfxFilepath, pfxPasswordについては環境変数でも設定可能です。（GINUE_USERNAME, GINUE_PASSWORD, GINUE_BASIC, GINUE_PFX_FILEPATH, GINUE_PFX_PASSWORD）
- 優先順位は 環境変数 < .netrc < .ginuerc < 引数

.ginuerc

コマンドを実行するディレクトリに.ginuercという設定ファイルを作成すると、ginue実行時に自動的に読み込まれてオプション指定を省略できます。プロジェクト単位で.ginuercを作成すると便利です。

フォーマットはJSON/JS/YAMLの3種類に対応しています。

.ginuerc.json

{
  "location": "kintone-settings",
  "domain": "ginue.cybozu.com",
  "username": "Administrator",
  "password": "myKintonePassword",
  "app": [10, 11, 12],
  "guest": 5
}

.ginuerc.js

module.exports = {
  location: 'kintone-settings',
  domain: 'ginue.cybozu.com',
  username: 'Administrator',
  password: 'myKintonePassword',
  app: [10, 11, 12],
  guest: 5,
}

.ginuerc.yml

  location: kintone-settings
  domain: ginue.cybozu.com
  username: Administrator
  password: myKintonePassword
  app:
    - 10
    - 11
    - 12
  guest: 5

envプロパティを使用すると、異なる環境のアプリをグルーピングできます。
- 各環境別にオブジェクトを作成し、プロパティは環境名として自由に設定します。(ex. development, production)
- ginue pull時には各環境ごとにディレクトリが作成され、配下にJSONファイルが保存されます。
  - デフォルトでは環境名＝ディレクトリ名
  - 各環境にlocationプロパティを指定すると、locationの値＝ディレクトリ名
  - トップレベルにlocationプロパティを指定すると、locationのディレクトリ配下に、各環境のサブディレクトリを作成
appプロパティにオブジェクトを指定すると、アプリIDではなくアプリ名のディレクトリにJSONが保存されます。
- その場合、各種ginueコマンドの引数にappNameオプションを指定することで、特定のアプリのみを処理できます。

{
  "location": "kintone-settings",
  "env": {
    "development": {
      "domain": "ginue-dev.cybozu.com",
      "username": "Administrator",
      "password": "myKintonePassword",
      "app": {
        "user": 128,
        "order": 129,
        "bill": 130
      },
      "basic": "Administrator:myBasicAuthPassword"
    },
    "production": {
      "location": "__PRODUCTION__",
      "domain": "ginue.cybozu.com",
      "username": "Administrator",
      "password": "myKintonePassword",
      "app": {
        "user": 10,
        "order": 11,
        "bill": 12
      },
      "guest": 5
    }
  }
}

ginue pull

カレントにアプリID名のディレクトリが作成され、その中に全JSONファイルが保存されます。
APIのレスポンス上は全JSONにrevision要素が含まれますが、保存される各JSONファイルではrevision要素が省略され、代わりにrevision.jsonというファイルを単独で作成します。（更新時のdiffがシンプルになるため）
previewオプションを指定すると、運用環境ではなくテスト環境のJSONファイルを取得します。運用環境へ反映する前の状態を確認したい場合は有効にしてください。
- .ginuercに"preview": trueを設定すると常時有効になります。

実行例

$ ginue pull -d ginue.cybozu.com -g 5 -a 10,11,12 -u Administrator
$ ginue pull -d ginue.cybozu.com -b Administrator -a 10,11,12 -u Administrator -l kintone-settings
$ ginue pull -A user --preview

ginue push

ginue pullで保存済みのJSONファイルを、kintoneにアップロードします。
環境名を単独で指定すれば同じ環境にアップロードします。
環境名をコロン区切りで<from>:<to>のように書くと、ローカルの<from>ディレクトリ配下に保存されたJSONファイルを<to>環境にアップロードします。
実行後はkintoneのテスト環境が変更された状態になるので、kintoneの設定画面で「アプリを更新」「変更を中止」ボタンをクリックするか、ginue deploy ginue resetコマンドを使用してください。

実行例

$ ginue push development
$ ginue push development:production
$ ginue push development:production -A user

ginue deploy

アプリの設定の運用環境への反映を行います。

実行例

$ ginue deploy development
$ ginue deploy development -A user

ginue reset

アプリの設定の変更をキャンセルします。

実行例

$ ginue reset development
$ ginue reset development -A user

ginue erd

⚠️実験的機能です。仕様は大きく変更される可能性があります。
ginue pullで保存済みのJSONファイルからkintoneアプリのルックアップ関係を解析して、ER図を作成します。
各envディレクトリの直下に、PlantUML形式のファイルerd.puを保存します。
画像ファイルは作成しないので、任意の方法でPlantUMLをレンダリングしてください。

実行例

$ ginue erd development