Skip to content

tagru ads ​

広告の集計・分析・監査・KW 分析・改善提案・AI レポート・キャンペーンを表示します(読み取りだけ)。 TAGRU の広告管理の画面と同じ数値を、ターミナルや AI エージェントから確認できます。

text
tagru ads [summary] [--days <1-366> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--platform <google|instagram|tiktok|x>] [--limit <n>] [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads analytics [--days <1-366> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--platform <google|instagram|tiktok|x>] [--campaign <id>] [--limit <n>] [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads audit [--days <1-90> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--platform <google|instagram|tiktok|x>] [--limit <n>] [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads kw [--mode <keyword|search-term|pmax>] [--filter <text>] [--days <1-90> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--limit <n>] [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads suggestions [--status <pending|done|hold|rejected>] [--priority <high|medium|low>] [--platform <google|instagram|tiktok|x>] [--limit <n>] [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads report [list] [--limit <n>] [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads report get <report-id> [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads campaigns [list] [--platform <google|instagram|tiktok|x>] [--status <active|paused|ended>] [--days <1-90>] [--limit <n>] [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads campaigns get <campaign-id> [--limit <n>] [--workspace <id>] [--service <id>] [--target <prod|test|localhost>] [--json]
tagru ads services [--workspace <id>] [--target <prod|test|localhost>] [--json]

サブコマンド ​

サブコマンド内容
summary(省略可)期間の集計・媒体別・今月の予算と、要対応(ムダと判定した消化・未対応の改善提案の件数)
analytics期間の KPI(前期間比つき)・媒体比較・キャンペーン別の実績
auditムダ消費の監査(CV が無い・CPA が高いキャンペーンやキーワードなど)
kwGoogle 広告のキーワード・検索語句・P-MAX の分析
suggestions保存済みの改善提案の一覧
report / report get保存済みの AI レポートの一覧と本文
campaigns / campaigns getキャンペーンの一覧(期間の実績つき)と詳細(日ごとの実績)
servicesクライアント / サービスの一覧(--service に渡す ID を確かめる)

オプション ​

オプション内容
--days <n>期間の日数(既定 30)。今日(端末のタイムゾーン)を終わりとする n 日間。summary / analytics は 1〜366、audit / kw は 1〜90。campaigns は一覧の実績の日数(1〜90)
--from <YYYY-MM-DD> --to <YYYY-MM-DD>期間を日付で指定する(両端を含む。両方指定する)。--days と同時には指定できません
--platform <name>媒体で絞り込む。google(Google 広告)/ instagram / tiktok / x
--campaign <id>analytics をキャンペーン 1 件に絞る(ID は tagru ads campaigns で確認)
--mode <name>kw の対象。keyword(登録キーワード、既定)/ search-term(検索語句)/ pmax(P-MAX)
--filter <text>kw をキーワードの部分一致で絞り込む(- で始まる文字は --filter=-語句 の形で指定)
--status <name>suggestions: pending(未対応)/ done(対応済み)/ hold(保留)/ rejected(却下)。campaigns: active(配信中)/ paused(停止中)/ ended(終了)
--priority <name>suggestions を優先度で絞り込む。high / medium / low
--limit <n>表示する件数(既定 20、1〜100)。summary は要対応の項目、analytics はキャンペーン別、campaigns get は日ごとの実績の件数
--workspace <id>ワークスペース(tagru use で保存した値より優先)
--service <id>サービス(ワークスペースを選んでいるときだけ。省略すると既定のサービス)。ID は tagru ads services で確認
-t, --target <name>接続先
--jsonJSON で出力する
  • 表示するだけです。キャンペーンの作成・変更、改善提案の生成・状態の変更、AI レポートの生成、除外キーワードの追加などは CLI からは行えません(TAGRU の画面から行ってください)
  • ワークスペースを選んでいない場合は、個人で連携した広告アカウントの値を出します
  • 広告管理の機能が使えない場合や、閲覧できる範囲の外のサービスを指定した場合は、その旨のメッセージを出して終了コード 1 で終わります(エラー)
  • TAGRU の画面で開いたときと同じく、実行すると広告媒体から新しい実績を取り込むことがあります(取り込みの間隔は画面と共通です)
  • audit のキーワード単位の項目と kw は、Google 広告へ問い合わせて集計するため、少し時間がかかることがあります
  • audit と kw は、同じ条件(期間・--mode・--platform・--workspace・--service)なら Google 広告へ問い合わせるのは 1 日 1 回だけで、同じ日の 2 回目以降はその日に取得した結果を返します(日付の区切りは日本時間。TAGRU の画面で開いた・同期した結果も同じものを使います)。--filter を変えたときも、その日に取得した結果から絞り込みます。目標 CPA と「候補から削除」した語句は、実行したときの設定で反映します

使い方 ​

bash
tagru ads                                  # 直近 30 日の集計と、今日の要対応
tagru ads --days 7 --platform google       # 期間と媒体を変える
tagru ads analytics --from 2026-09-01 --to 2026-09-30   # 期間を日付で指定し、前期間(直前の同じ日数)と比べる
tagru ads audit --days 14                  # ムダ消費の監査
tagru ads kw --mode search-term --filter 靴  # 検索語句の分析(部分一致で絞り込む)
tagru ads suggestions --status pending     # 未対応の改善提案
tagru ads report                           # AI レポートの一覧
tagru ads report get <report-id>           # AI レポートの本文
tagru ads campaigns --status active        # 配信中のキャンペーン
tagru ads campaigns get <campaign-id>      # キャンペーンの詳細と日ごとの実績
tagru ads services                         # サービスの一覧
tagru ads --service <service-id>           # 既定以外のサービスの集計

出力例 ​

text
$ tagru ads --limit 2
ワークスペース: ws-xxxx
サービス: (既定)
期間: 2026-09-05 〜 2026-10-04(30 日)
消化額: ¥240,000
表示回数: 60,000
クリック: 2,400
CV: 60
CTR: 4%
CPC: ¥100
CPA: ¥4,000

媒体別
媒体       連携    消化額  表示回数  クリック  CV     CPA
Google     済    ¥180,000    45,000     1,800  50  ¥3,600
Instagram  済     ¥60,000    15,000       600  10  ¥6,000
TikTok     未          ¥0         0         0   0       -

今月の予算(2026-10)
月予算: ¥500,000
消化額: ¥30,000
残予算: ¥470,000
着地予想: ¥232,500

要対応(2026-10-04 時点)
ムダと判定した消化額: ¥5,400
未対応の改善提案: 3 件
種類           媒体    キャンペーン      キーワード      消化額  CV  理由
CV0キーワード  Google  検索キャンペーン  サンプル語句 1  ¥1,800   0  CV が無いまま消化しています
CV0キーワード  Google  検索キャンペーン  サンプル語句 2  ¥3,600   0  CV が無いまま消化しています
ほか 1 件あります(--limit で増やせます)
  • 要対応は 1 日に 1 回集計した結果です(時点 の日付)。期間のオプションは要対応には影響しません
  • 予算が上限を超えそうなとき・下限に届いていないときは 注意: の行が出ます
text
$ tagru ads analytics
ワークスペース: ws-xxxx
サービス: (既定)
期間: 2026-09-05 〜 2026-10-04(30 日)
前期間: 2026-08-06 〜 2026-09-04
消化額: ¥240,000(前期間比 +9.1%)
表示回数: 60,000(前期間比 +6.7%)
クリック: 2,400(前期間比 +6.7%)
CV: 60(前期間比 +15.4%)
CTR: 4%(前期間比 ±0%)
CPC: ¥100(前期間比 +2%)
CVR: 2.5%(前期間比 +8.2%)
CPA: ¥4,000(前期間比 -5.5%)
CV 値: ¥960,000(前期間比 +9.1%)
ROAS: 400%(前期間比 ±0%)

媒体比較
媒体         消化額  シェア  前期間比  CV     CPA
Google     ¥180,000     75%      +20%  50  ¥3,600
Instagram   ¥60,000     25%    -14.3%  10  ¥6,000

キャンペーン別
ID        媒体       キャンペーン        消化額  前期間比  CV     CPA
cmp-0001  Google     検索キャンペーン  ¥180,000      +20%  50  ¥3,600
cmp-0002  Instagram  秋のセール         ¥60,000    -14.3%  10  ¥6,000
text
$ tagru ads audit --limit 2
ワークスペース: ws-xxxx
サービス: (既定)
期間: 2026-09-05 〜 2026-10-04(30 日)
ムダと判定した消化額: ¥10,800

種類別
種類             件数  消化額
CV0キャンペーン     1  ¥5,400
CV0キーワード       2  ¥5,400

項目
種類           媒体    キャンペーン      キーワード      消化額  CV  理由
CV0キーワード  Google  検索キャンペーン  サンプル語句 1  ¥1,800   0  CV が無いまま消化しています
CV0キーワード  Google  検索キャンペーン  サンプル語句 2  ¥3,600   0  CV が無いまま消化しています
ほか 1 件あります(--limit で増やせます)
text
$ tagru ads kw --mode search-term
ワークスペース: ws-xxxx
サービス: (既定)
期間: 2026-09-05 〜 2026-10-04(30 日)
対象: 検索語句
目標 CPA: ¥3,000
件数: 2
キーワード        マッチ  分類      キャンペーン       消化額  クリック  CV     CPA
サンプル 靴 通販  PHRASE  除外候補  検索キャンペーン   ¥8,000        40   0       -
サンプル 靴       EXACT   効率良好  検索キャンペーン  ¥18,000       120  12  ¥1,500
text
$ tagru ads suggestions --limit 2
ワークスペース: ws-xxxx
サービス: (既定)
ID       生成日時          優先度  状態    媒体       タイトル
sg-0001  2026-10-03 09:00  高      未対応  Google     検索キャンペーンの日予算を増やす
sg-0002  2026-10-01 09:00  中      保留    Instagram  クリエイティブを差し替える
続きがあります(--limit で増やせます)

説明・期待効果は --json で確認できます。改善提案の生成・状態の変更は TAGRU の画面から行ってください。
text
$ tagru ads report get rp-0002
ワークスペース: ws-xxxx
サービス: (既定)
ID: rp-0002
期間: 2026-09-01 〜 2026-09-30
生成日時: 2026-10-01 09:00
本文: ## 現状サマリ
  消化は計画どおりです。
  ## 次のアクション
  - 検索キャンペーンの日予算を見直す
text
$ tagru ads campaigns
ワークスペース: ws-xxxx
サービス: (既定)
実績の期間: 2026-09-05 〜 2026-10-04
ID        媒体       状態    キャンペーン      日予算    消化額  CV     CPA
cmp-0001  Google     配信中  検索キャンペーン  ¥6,000  ¥180,000  50  ¥3,600
cmp-0002  Instagram  停止中  秋のセール        ¥2,000   ¥60,000  10  ¥6,000

`tagru ads campaigns get <ID>` で詳細と日ごとの実績を表示できます。
text
$ tagru ads campaigns get cmp-0001
ワークスペース: ws-xxxx
サービス: (既定)
ID: cmp-0001
キャンペーン: 検索キャンペーン
媒体: Google
状態: 配信中
目的: SEARCH
日予算: ¥6,000
配信期間: 2026-09-01 〜
更新日時: 2026-10-02 10:00

日ごとの実績(新しい順)
日付        消化額  表示回数  クリック  CV
2026-10-03  ¥5,800     1,450        58   1
2026-10-02  ¥6,000     1,500        60   2
text
$ tagru ads services
ワークスペース: ws-xxxx
   サービス ID  クライアント  サービス
*  svc-0001     (未分類)    既定
   svc-0002     サンプル商事  通販サイト
   svc-0003     サンプル商事  実店舗

* は既定のサービス(--service を省略したときに使います)。`--service <サービス ID>` で切り替えられます。

サービスの選び方 ​

広告はワークスペースの中で「クライアント → サービス」に分けて管理しています。

  1. tagru ads services で、見られるサービスとその ID を確かめる(閲覧できる範囲のクライアントだけが出ます)
  2. 各コマンドに --service <サービス ID> を付ける。省略すると既定のサービス(* の付いたもの)を使います

--service はワークスペースを選んでいるときだけ指定できます。個人の広告にはサービスがありません。

--json ​

tagru ads の JSON は、共通の外枠 に serviceId(指定したサービス。省略したときは null)を加えます。 summary / analytics / audit / kw / report get / campaigns get は詳細の外枠(item)、 suggestions / report / campaigns / services は一覧の外枠(items)です。

  • 媒体(platform)は google / instagram / tiktok / x です
  • 金額は円、ctr / cvr / roas は %、日付は YYYY-MM-DD、日時は ISO 8601(タイムゾーン付き)です
  • 率・単価は分母が 0 のとき(表示回数・クリック・CV が無いとき)null です
  • item の中の一覧(要対応・監査の項目・KW・キャンペーン別・日ごとの実績)は { "total", "hasMore", "items" } の形で、items は --limit 件までです(total は全体の件数)

tagru ads summary --json ​

jsonc
{
  "target": "prod",
  "workspaceId": "ws-xxxx",
  "serviceId": null,
  "item": {
    "period": { "startDate": "2026-09-05", "endDate": "2026-10-04", "days": 30 },
    "platform": null,                     // --platform で絞ったときの媒体
    "totals": {
      "spend": 240000, "spendGross": 264000, "impressions": 60000, "clicks": 2400,
      "conversions": 60, "ctr": 4, "cpc": 100, "cpa": 4000
    },
    "platforms": [
      { "platform": "google", "connected": true, "spend": 180000, "spendGross": 198000, "impressions": 45000,
        "clicks": 1800, "conversions": 50, "ctr": 4, "cpc": 100, "cpa": 3600 }
    ],
    "budget": {                           // 今月の予算の状況。取得できなければ null
      "month": "2026-10", "monthlyBudget": 500000, "monthSpend": 30000, "monthConversions": 8,
      "remainingBudget": 470000, "projectedSpend": 232500, "belowMin": false, "aboveMax": false
    },
    "brief": {
      "date": "2026-10-04",
      "generatedAt": "2026-10-04T08:30:00+09:00",
      "totalWasteCost": 5400,
      "pendingSuggestions": 3,
      "googleUnavailable": false,
      "total": 3,
      "hasMore": true,
      "items": [
        {
          "category": "cv0_keyword", "platform": "google", "campaignId": null, "campaignName": "検索キャンペーン",
          "adGroupName": "広告グループ A", "keyword": "サンプル語句 1", "matchType": "PHRASE",
          "cost": 1800, "clicks": 12, "conversions": 0, "cpa": null, "message": "CV が無いまま消化しています"
        }
      ]
    }
  }
}
項目型内容
totals / platforms[]objectspend(消化額)spendGross(マージン設定を反映した消化額。設定が無ければ spend と同じ)impressions clicks conversions ctr cpc cpa。platforms[] は platform と connected(連携済みか)も持つ
budgetobject | nullmonth(YYYY-MM)monthlyBudget(未設定なら null)monthSpend monthConversions remainingBudget projectedSpend(着地予想)belowMin(下限予算に届いていない)aboveMax(上限予算を超える見込み)
brief.date / brief.generatedAtstring | null要対応を集計した日・日時
brief.totalWasteCostnumber | nullムダと判定した消化額
brief.pendingSuggestionsnumber | null未対応の改善提案の件数
brief.googleUnavailablebooleanGoogle 広告のデータを取得できず、キーワード単位の項目が含まれていない
brief.items[]object要対応の項目(下の「監査・要対応の項目」)

監査・要対応の項目 ​

項目型内容
categorystring種類(cv0_campaign / cv0_keyword / cpa_over / cpa_over_campaign / negative_candidate / budget_limited / cost_declining / cpa_worsened)
platformstring | null媒体
campaignIdstring | nullキャンペーンの ID(キャンペーン単位の項目だけ)
campaignNamestringキャンペーン名
adGroupName / keyword / matchTypestring | null広告グループ・キーワード・マッチタイプ(キーワード単位の項目だけ)
cost / clicks / conversionsnumber | null消化額・クリック・CV
cpanumber | nullCPA(CPA の種類だけ)
messagestring判定の理由

tagru ads analytics --json ​

jsonc
{
  "target": "prod",
  "workspaceId": "ws-xxxx",
  "serviceId": null,
  "item": {
    "period": { "startDate": "2026-09-05", "endDate": "2026-10-04", "days": 30 },
    "previousPeriod": { "startDate": "2026-08-06", "endDate": "2026-09-04" },   // 無ければ null
    "platform": null,
    "campaignId": null,
    "totals": {
      "spend": 240000, "impressions": 60000, "clicks": 2400, "conversions": 60, "ctr": 4, "cpc": 100,
      "cvr": 2.5, "cpa": 4000, "conversionValue": 960000, "roas": 400
    },
    "previousTotals": { ... },            // 前期間の合計(同じ項目)。無ければ null
    "platforms": [                        // 媒体比較(--campaign のときは空)
      { "platform": "google", "spendShare": 75, "current": { ... }, "previous": { ... } }
    ],
    "campaigns": {                        // キャンペーン別(当期間の消化額の多い順)
      "total": 2,
      "hasMore": false,
      "items": [
        { "id": "cmp-0001", "name": "検索キャンペーン", "platform": "google", "status": "active", "current": { ... }, "previous": { ... } }
      ]
    }
  }
}
  • 指標(totals / current / previous)の項目: spend impressions clicks conversions ctr cpc cvr cpa conversionValue(CV 値。取得できない媒体・期間は null)roas(%。CV 値が無ければ null)
  • spendShare は当期間の消化額のシェア(%)

tagru ads audit --json ​

jsonc
{
  "target": "prod",
  "workspaceId": "ws-xxxx",
  "serviceId": null,
  "item": {
    "period": { "startDate": "2026-09-05", "endDate": "2026-10-04", "days": 30 },
    "platform": null,
    "platforms": ["google", "instagram"],     // 集計した媒体
    "totalWasteCost": 10800,
    "categories": [ { "category": "cv0_campaign", "count": 1, "totalCost": 5400 } ],   // 集計した種類ごと
    "googleUnavailable": false,
    "total": 3,
    "hasMore": true,
    "items": [ { "category": "cv0_keyword", ... } ]   // 監査・要対応の項目(上の表)
  }
}

tagru ads kw --json ​

jsonc
{
  "target": "prod",
  "workspaceId": "ws-xxxx",
  "serviceId": null,
  "item": {
    "mode": "search-term",
    "period": { "startDate": "2026-09-05", "endDate": "2026-10-04", "days": 30 },
    "targetCpa": 3000,                    // 目標 CPA。未設定なら null
    "total": 2,
    "hasMore": false,
    "items": [
      {
        "keyword": "サンプル 靴 通販", "matchType": "PHRASE", "campaignId": "111", "campaignName": "検索キャンペーン",
        "adGroupName": "広告グループ A", "status": "ENABLED", "classification": "exclude",
        "cost": 8000, "impressions": 800, "clicks": 40, "conversions": 0, "cpa": null, "cvr": 0, "cpc": 200
      }
    ]
  }
}
項目型内容
statusstring | null登録キーワードの状態(ENABLED / PAUSED)。登録キーワード以外は null
classificationstring分類(exclude 除外候補 / add 追加候補 / warning 要注意 / efficient 効率良好 / neutral)

tagru ads suggestions --json ​

jsonc
{
  "target": "prod",
  "workspaceId": "ws-xxxx",
  "serviceId": null,
  "items": [
    {
      "id": "sg-0001",
      "platform": "google",
      "priority": "high",                 // high / medium / low
      "status": "pending",                // pending / done / hold / rejected
      "actionType": "adjust_budget",      // exclude_keyword / adjust_bid / add_keyword / adjust_budget / remove_negative_keyword / split_test / consolidate
      "title": "検索キャンペーンの日予算を増やす",
      "description": "CPA が目標より低く、予算で表示機会を逃しています。",
      "expectedEffect": "CV が 1 割ほど増える見込み",
      "generatedAt": "2026-10-03T09:00:00+09:00",
      "updatedAt": "2026-10-03T09:00:00+09:00"
    }
  ],
  "count": 1,
  "hasMore": true
}

tagru ads report --json / tagru ads report get --json ​

jsonc
// 一覧(items)
{ "id": "rp-0002", "startDate": "2026-09-01", "endDate": "2026-09-30", "generatedAt": "2026-10-01T09:00:00+09:00",
  "wasteAuditIncluded": true, "suggestionsIncluded": 3 }
// 本文(item): 一覧の項目に report(Markdown)を加える
{ ..., "report": "## 現状サマリ\n消化は計画どおりです。\n..." }
項目型内容
wasteAuditIncludedbooleanムダ消費の監査の結果を含めて生成したか
suggestionsIncludednumber | null生成に使った改善提案の件数
reportstring本文(Markdown。get のみ)

tagru ads campaigns --json / tagru ads campaigns get --json ​

jsonc
// 一覧(items)
{
  "id": "cmp-0001", "platform": "google", "name": "検索キャンペーン", "status": "active", "objective": "SEARCH",
  "dailyBudget": 6000, "startDate": "2026-09-01", "endDate": null, "updatedAt": "2026-10-02T10:00:00+09:00",
  "metrics": { "days": 30, "spend": 180000, "impressions": 45000, "clicks": 1800, "conversions": 50, "cpa": 3600 }
}
// 詳細(item): metrics の代わりに日ごとの実績(新しい順に --limit 日分)
{
  "id": "cmp-0001", ..., "updatedAt": "2026-10-02T10:00:00+09:00",
  "daily": { "total": 2, "hasMore": false, "items": [ { "date": "2026-10-03", "spend": 5800, "impressions": 1450, "clicks": 58, "conversions": 1 } ] }
}
  • status は active(配信中)/ paused(停止中)/ ended(終了)
  • metrics は --days 日間の実績(days は実績のあった日数。cpa は CV が無ければ null)

tagru ads services --json ​

jsonc
{
  "target": "prod",
  "workspaceId": "ws-xxxx",
  "serviceId": null,
  "items": [
    { "id": "svc-0001", "name": "既定", "clientId": "cl-0001", "clientName": "(未分類)", "isDefault": true }
  ],
  "count": 1,
  "hasMore": false
}

エラー ​

メッセージ対処
エラー(403): 広告管理を利用できません(広告管理の機能が有効になっていません)。…そのワークスペース(個人)では広告管理が使えません。TAGRU の運営へお問い合わせください
エラー(403): このクライアント(サービス)の広告を見る権限がありません。…閲覧できる範囲の外です。tagru ads services で見られるサービスを確かめる
エラー(404): サービスが見つかりません。…--service の ID を tagru ads services で確かめる
エラー(400): 広告アカウントが連携されていません。…TAGRU の広告管理の画面で連携する(kw と、--platform google の audit は Google 広告の連携が必要)
--service はワークスペースを選んでいるときだけ指定できます…tagru use か --workspace でワークスペースを選ぶ

--json のときは { "error": { "status": 403, "code": "forbidden", "message": "..." } } の形です(エラーと終了コード)。