pleasanter-site-dev-cli

Pleasanter の getsite / updatesitesettings API を使って、サイト設定のバックアップ、複数サイトの収集、Scripts / ServerScripts 更新を行う CLI です。

対象 API:

• POST /api/items/{siteId}/getsite
• POST /api/items/{siteId}/updatesitesettings

Pleasanter のマニュアル:

• https://pleasanter.org/ja/manual/api-site-get
• https://pleasanter.org/ja/manual/api-update-sitesettings

前提

• Node.js 18 以上
• API キーに対象サイトの管理権限があること
• base-url は https://example.com または https://pleasanter.net/fs のように、Pleasanter のルートまでを指定すること

利用者向け

npm install --save-dev @yamada28go/pleasanter-site-dev-cli

package.json の script やローカル作業用 CLI として使う前提なら、通常は dependencies ではなく devDependencies に入れる方が自然です。

単発で試すだけなら npx でも実行できます。

npx @yamada28go/pleasanter-site-dev-cli help

このリポジトリ自体の開発手順は DEVELOPING.md を参照してください。

コマンド

バックアップ

pleasanter-site-dev backup \
  --base-url https://example.com \
  --site-id 12345 \
  --api-key-file ~/.config/pleasanter/api-key.txt

出力先を固定したい場合:

pleasanter-site-dev backup \
  --base-url https://example.com \
  --site-id 12345 \
  --api-key-file ~/.config/pleasanter/api-key.txt \
  --output-file ./backups/site-settings.json

共通オプションを 1 つの設定ファイルにまとめる場合:

pleasanter-site-dev backup --settings ./examples/cli-settings.json

更新

更新前に自動でバックアップを作成し、その後 Scripts / ServerScripts を更新します。

pleasanter-site-dev push \
  --base-url https://example.com \
  --site-id 12345 \
  --api-key-file ~/.config/pleasanter/api-key.txt \
  --config ./examples/site-settings.config.json \
  --backup-retention 10

共通オプションを settings ファイルに寄せる場合:

pleasanter-site-dev push --settings ./examples/cli-settings.json

バックアップを無効にする場合:

pleasanter-site-dev push \
  --base-url https://example.com \
  --site-id 12345 \
  --api-key-file ~/.config/pleasanter/api-key.txt \
  --config ./examples/site-settings.config.json \
  --skip-backup

API に送る JSON を確認だけしたい場合:

pleasanter-site-dev push \
  --base-url https://example.com \
  --site-id 12345 \
  --api-key-file ~/.config/pleasanter/api-key.txt \
  --config ./examples/site-settings.config.json \
  --dry-run

複数サイト収集

グルーコード生成用の元データをまとめて取得したい場合は collect を使います。

pleasanter-site-dev collect \
  --base-url https://example.com \
  --site-ids 12345,23456,34567 \
  --api-key-file ~/.config/pleasanter/api-key.txt \
  --output-file ./backups/sites.json

出力ファイルは { "Sites": [...] } 形式です。実際には getsite の取得結果がそのまま並びます。

{
  "Sites": [
    {
      "TenantId": 1,
      "SiteId": 12345,
      "Title": "記録テーブル",
      "Comments": [],
      "SiteSettings": {
        "ReferenceType": "Results",
        "Columns": [],
        "Scripts": [],
        "ServerScripts": []
      }
    }
  ]
}

補足 Pleasanter の取得結果に Comments: "[]" が含まれる場合だけ、後段で読みやすいように Comments: [] に補正して出力します。

APIキーの渡し方

package.json の script や CI から呼び出す場合は、--api-key で値を直接渡すよりも、環境変数または --api-key-file / PLEASANTER_API_KEY_FILE を使う方が安全です。

• 推奨: PLEASANTER_API_KEY
• 推奨: PLEASANTER_API_KEY_FILE
• 互換用: --api-key

--api-key-file と PLEASANTER_API_KEY_FILE は、APIキーだけを書いたテキストファイルを読み込みます。末尾改行は自動で取り除きます。

export PLEASANTER_API_KEY_FILE=~/.config/pleasanter/api-key.txt
pleasanter-site-dev backup --base-url https://example.com --site-id 12345

package.json では、秘密値そのものを埋め込まずにコマンドだけを定義してください。

{
  "scripts": {
    "pleasanter:push": "pleasanter-site-dev push --base-url https://example.com --site-id 12345 --config ./examples/site-settings.config.json"
  }
}

実行設定ファイル

CLI の共通オプションは --settings または PLEASANTER_SETTINGS_FILE で JSON から読み込めます。コマンドライン引数が最優先で、その次に settings ファイル、最後に環境変数を使います。

{
  "baseUrl": "https://example.com",
  "siteId": 12345,
  "siteIds": [12345, 23456, 34567],
  "apiKeyFile": "./secrets/api-key.txt",
  "config": "./site-settings.config.json",
  "backupDir": "./backups",
  "backupRetention": 10
}

使えるキー:

• baseUrl
• siteId
• siteIds
• apiKey
• apiKeyFile
• apiVersion
• logLevel
• backupDir
• backupRetention
• outputFile
• config
• skipBackup
• dryRun

apiKeyFile、config、backupDir、outputFile の相対パスは settings ファイル基準で解決されます。 backupRetention は push 実行時の自動バックアップ保持数です。未指定なら 10 世代を保持します。

更新設定ファイル

設定ファイルは JSON です。Body を直接書くか、BodyFile で外部ファイルを参照できます。BodyFile の相対パスは設定ファイル基準で解決されます。

{
  "scripts": [
    {
      "Id": 1,
      "Title": "sample script",
      "BodyFile": "./scripts/sample-script.js",
      "ScriptAll": true
    }
  ],
  "serverScripts": [
    {
      "Id": 9,
      "Title": "sample server script",
      "Name": "SampleServerScript9",
      "BodyFile": "./server-scripts/sample-server-script.csx",
      "ServerScriptWhenloadingSiteSettings": true
    }
  ]
}

push 時には BodyFile を読み込んで Body に展開し、Pleasanter の updatesitesettings に以下のような形で送信します。

{
  "ApiVersion": 1.1,
  "ApiKey": "xxxxx",
  "Scripts": [
    {
      "Id": 1,
      "Title": "sample script",
      "Body": "console.log('sample');",
      "ScriptAll": true
    }
  ],
  "ServerScripts": [
    {
      "Id": 9,
      "Title": "sample server script",
      "Name": "SampleServerScript9",
      "Body": "context.Log('sample');",
      "ServerScriptWhenloadingSiteSettings": true
    }
  ]
}

環境変数

以下でも指定できます。

export PLEASANTER_BASE_URL=https://example.com
export PLEASANTER_SITE_ID=12345
export PLEASANTER_API_KEY=xxxxx
export PLEASANTER_API_KEY_FILE=~/.config/pleasanter/api-key.txt
export PLEASANTER_API_VERSION=1.1
export PLEASANTER_BACKUP_RETENTION=10
export PLEASANTER_SETTINGS_FILE=./examples/cli-settings.json

バックアップファイル

バックアップには以下を保存します。

• 取得した site 全体
• site.SiteSettings.Scripts
• site.SiteSettings.ServerScripts

出力先のデフォルトは ./backups です。