@dac-tech-team-tw/gtm-cli 1.6.2 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +161 -18
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,44 +1,187 @@
1
- # @dac-tech-team-tw/gtm-cli
1
+ # GTM CLI
2
2
 
3
- Command-line interface for Google Tag Manager. See the [project documentation](https://github.com/dac-tech-team-tw/gtm-cli) for configuration and commands.
3
+ GTM CLI 是以 Deno 和 Cliffy 建立的 Google Tag Manager 命令列工具。這個分支由 [dac-tech-team-tw](https://github.com/dac-tech-team-tw/gtm-cli) 維護,源自 [owntag/gtm-cli](https://github.com/owntag/gtm-cli)。可用來管理帳戶、容器、工作區及代碼等資源,也適合自動化與 CI/CD。
4
4
 
5
- ## Installation
5
+ ## 安裝
6
6
 
7
- Node.js 16 or newer and npm are required. Supported platforms are Windows x64, macOS x64 and arm64, and Linux x64. Installing downloads the matching binary for the package version from the project's GitHub Releases, so network access to GitHub and its release asset host is required. npm lifecycle scripts must be enabled for the automatic download; if scripts were disabled, the wrapper attempts the download on first use.
7
+ 預先編譯的發行檔支援 macOS Apple Silicon/Intel、Linux x64 與 Windows x64。安裝腳本和 npm 安裝都需要本分支已有相應的 GitHub Release 資產。
8
+
9
+ ### macOS / Linux
8
10
 
9
11
  ```bash
10
- npm install -g @dac-tech-team-tw/gtm-cli
11
- gtm --help
12
+ curl -fsSL https://raw.githubusercontent.com/dac-tech-team-tw/gtm-cli/main/install.sh | bash
13
+ ```
14
+
15
+ ### Windows x64
16
+
17
+ 在 PowerShell 執行:
18
+
19
+ ```powershell
20
+ irm https://raw.githubusercontent.com/dac-tech-team-tw/gtm-cli/main/install.ps1 | iex
12
21
  ```
13
22
 
14
- Alternatively, run without a global installation:
23
+ 腳本將 `gtm.exe` 安裝至 `%LOCALAPPDATA%\Programs\gtm`,並加入使用者 PATH;若其他終端機尚未取得新的 PATH,請重新開啟終端機。
24
+
25
+ ### npm
26
+
27
+ `@dac-tech-team-tw/gtm-cli` 已發布至 npm。安裝時會下載套件版本對應的 GitHub Release 二進位檔,因此該版本的 Release 資產必須存在。
15
28
 
16
29
  ```bash
17
- npx @dac-tech-team-tw/gtm-cli --help
30
+ npm install -g @dac-tech-team-tw/gtm-cli
31
+ # 或指定已發布的版本
32
+ npm install -g @dac-tech-team-tw/gtm-cli@<版本>
18
33
  ```
19
34
 
20
- For reproducible CI, pin a released version, for example:
35
+ ### 手動下載或從原始碼建置
36
+
37
+ 從本分支的 [GitHub Releases](https://github.com/dac-tech-team-tw/gtm-cli/releases) 下載對應檔案:
38
+
39
+ | 平台 | 檔案 |
40
+ | --- | --- |
41
+ | macOS Apple Silicon | `gtm-darwin-arm64` |
42
+ | macOS Intel | `gtm-darwin-x64` |
43
+ | Linux x64 | `gtm-linux-x64` |
44
+ | Windows x64 | `gtm-windows-x64.exe` |
45
+
46
+ macOS/Linux 可將下載檔重新命名為 `gtm`、使用 `chmod +x gtm` 賦予執行權限,再移至 PATH 中的目錄。Windows 可將檔案命名為 `gtm.exe` 並放入 PATH。
47
+
48
+ 安裝 [Deno 2](https://deno.com/) 後,也可自行建置:
21
49
 
22
50
  ```bash
23
- npm install -g @dac-tech-team-tw/gtm-cli@1.6.2
51
+ git clone https://github.com/dac-tech-team-tw/gtm-cli.git
52
+ cd gtm-cli
53
+ deno task compile
24
54
  ```
25
55
 
26
- ## Usage
56
+ 產生的執行檔為 `gtm`(Windows 為 `gtm.exe`)。原始碼建置的 OAuth 憑證需自行提供,詳見下方認證說明。
57
+
58
+ ## 認證
59
+
60
+ ### 瀏覽器 OAuth
27
61
 
28
62
  ```bash
29
63
  gtm auth login
64
+ gtm auth status
65
+ ```
66
+
67
+ 登入流程會開啟瀏覽器,並使用 `http://localhost:8085/callback` 接收回呼。使用的 Google 帳戶必須具備所需的 GTM 權限。
68
+
69
+ 自行建置或執行原始碼時,請在 Google Cloud 專案啟用 Tag Manager API,建立 OAuth 2.0 用戶端並設定 `GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`。若使用 Web application 類型,請將上述回呼網址加入授權重新導向 URI。執行 `deno task start` 時也可在專案根目錄的 `.env` 提供這些變數;已編譯程式則可使用執行環境變數。發行建置可由維護者在 CI 中嵌入用戶端憑證。
70
+
71
+ ### 服務帳戶
72
+
73
+ 啟用 Tag Manager API,建立服務帳戶及 JSON 金鑰,並在 GTM 中授予該服務帳戶所需的帳戶或容器權限:
74
+
75
+ ```bash
76
+ gtm auth login --service-account /path/to/key.json
77
+ # 或設定環境變數,供後續指令使用
78
+ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
30
79
  gtm accounts list
31
- gtm containers list --account-id <account-id>
32
80
  ```
33
81
 
34
- Google Tag Manager access and appropriate credentials are required. Use `gtm auth login --help` for authentication options.
82
+ PowerShell 使用 `$env:GOOGLE_APPLICATION_CREDENTIALS = 'C:\path\to\key.json'`。此環境變數優先於其他認證方式;妥善保管金鑰,不要提交至版本庫。
35
83
 
36
- ## Publishing setup
84
+ ```bash
85
+ gtm auth status
86
+ gtm auth logout
87
+ ```
88
+
89
+ 登出會清除已儲存的認證設定;服務帳戶金鑰檔不會被刪除,環境變數也不會被清除。
90
+
91
+ ## 快速開始與設定
92
+
93
+ ```bash
94
+ gtm --help
95
+ gtm accounts list
96
+ gtm containers list --account-id 123456
97
+ gtm workspaces list --account-id 123456 --container-id 789
98
+ gtm tags list --account-id 123456 --container-id 789 --workspace-id 1
99
+ ```
100
+
101
+ 可先執行互動式設定選擇預設帳戶、容器及工作區:
102
+
103
+ ```bash
104
+ gtm config setup
105
+ gtm config get
106
+ gtm config set defaultAccountId 123456
107
+ gtm config set defaultContainerId 789
108
+ gtm config set defaultWorkspaceId 1
109
+ gtm config unset defaultWorkspaceId
110
+ ```
111
+
112
+ 可設定的鍵為 `defaultAccountId`、`defaultContainerId`、`defaultWorkspaceId` 和 `outputFormat`(`table`、`json`、`compact`)。各指令支援的選項與預設值可能不同,請用 `--help` 確認;部分操作即使設定預設值,仍要求明確提供資源 ID。
113
+
114
+ 設定與認證檔預設位於 macOS/Linux 的 `~/.config/gtm-cli`,Windows 的 `%APPDATA%\gtm-cli`;可用 `GTM_CLI_CONFIG_DIR` 覆寫,也支援 `XDG_CONFIG_HOME`。請保護這些檔案中的憑證。
115
+
116
+ ## 常用指令
117
+
118
+ 以下假設已設定適當的預設帳戶、容器與工作區。實際可用操作及必要參數請參閱各指令的 `--help`。
119
+
120
+ ```bash
121
+ # 容器與工作區
122
+ gtm containers list
123
+ gtm containers create --name "My Container" --type web
124
+ gtm workspaces list
125
+ gtm workspaces create --name "Feature Branch"
126
+ gtm workspaces status --workspace-id 1
127
+
128
+ # 工作區資源
129
+ gtm tags list --output json
130
+ gtm tags get --tag-id 42
131
+ gtm triggers list
132
+ gtm variables list
133
+ gtm folders list
134
+
135
+ # 容器版本:發布會變更正式環境
136
+ gtm version-headers list
137
+ gtm versions live
138
+ gtm versions create --name "Release"
139
+ gtm versions publish --version-id 42
140
+ ```
141
+
142
+ 其他指令群組包括 `environments`、`built-in-variables`、`clients`、`templates`、`transformations`、`zones`、`destinations`、`gtag-configs` 與 `user-permissions`。使用 `gtm <指令> --help` 查看操作;`gtm agent guide` 提供代理程式使用指南。許多清單或查詢指令接受 `--output json`、`table` 或 `compact`;`--quiet` 可減少非必要輸出,`--no-color` 可停用色彩。
143
+
144
+ 要傳 JSON 或 `.tpl` 範本時,建議先儲存成 UTF-8 檔,再用 `--config-file`、`--container-access-file` 或 `--template-data-file` 傳檔案路徑,避免 shell 引號和命令列長度限制。檔案旗標不可與對應的行內旗標同時使用。
145
+
146
+ Windows PowerShell 5.1 寫檔請用 `Set-Content -Encoding UTF8`;預設的 `Set-Content` 和 `>` 可能產生非 UTF-8 檔案。
147
+
148
+ ```bash
149
+ gtm upgrade --check
150
+ gtm upgrade
151
+ ```
152
+
153
+ `upgrade` 可檢查或安裝較新版本;升級依賴對應平台的 Release 資產。
154
+
155
+ ## 開發
156
+
157
+ 需要 Deno 2。從專案目錄執行:
158
+
159
+ ```bash
160
+ deno task start --help # 執行 CLI
161
+ deno task dev # 監看檔案並執行
162
+ deno task check # 型別檢查
163
+ deno task lint # 靜態檢查
164
+ deno task fmt # 格式化
165
+ deno task compile # 建置目前平台的執行檔
166
+ ```
167
+
168
+ `deno.json` 是 CLI 版本來源。需要 OAuth 時,請依認證章節設定本機環境變數或 `.env`;勿將憑證提交至版本庫。
169
+
170
+ ## 發行與 npm trusted publishing
171
+
172
+ 維護者可在乾淨的 `main` 分支執行以下其中一項(此操作會推送至 `origin`):
173
+
174
+ ```bash
175
+ deno task release patch
176
+ deno task release minor
177
+ deno task release major
178
+ deno task release 2.0.0
179
+ ```
37
180
 
38
- The release script synchronizes `npm/package.json` with the version in `deno.json` and creates a version tag. The `release.yml` GitHub Actions workflow builds all four binaries, uploads them to the GitHub release, then publishes the npm package. Do not publish a package version before its matching `v<version>` release assets exist.
181
+ 腳本會拉取 `origin/main`、同步更新 `deno.json` 與 `npm/package.json` 的版本、執行型別檢查、建立提交與 `v` 標籤,並推送分支及標籤。標籤會觸發 `.github/workflows/release.yml`,建置各平台二進位檔、建立 GitHub Release,並在資產上傳後透過 OIDC 發布 npm 套件。若要讓發行檔支援內建 OAuth,須先在 GitHub repository secrets 設定 `GOOGLE_CLIENT_ID` 與 `GOOGLE_CLIENT_SECRET`;請使用本分支自己的 Google OAuth 用戶端。
39
182
 
40
- Configure npm trusted publishing for `@dac-tech-team-tw/gtm-cli` with GitHub organization/user `dac-tech-team-tw`, repository `gtm-cli`, and workflow filename `release.yml`. The package must exist on npm before configuring its trusted publisher; if necessary, an authorized maintainer must perform the initial public publish after the matching release assets are available. Subsequent workflow publishes use GitHub Actions OIDC and do not require an npm token. The workflow also requires the `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` repository secrets for release builds.
183
+ npm 發布前,維護者須擁有 `@dac-tech-team-tw` scope 的發布權限。在 npm 套件設定中新增 GitHub Actions trusted publisher,指定擁有者 `dac-tech-team-tw`、儲存庫 `gtm-cli` 與工作流程檔名 `release.yml`,並允許直接執行 `npm publish`;若工作流程使用受保護環境,也須指定相符的環境。新設定須在兩天內成功發布一次,否則會過期。OIDC 發布需要工作流程具備 `id-token: write` 權限及支援 trusted publishing 的 npm 版本。發布前亦須確認 npm 套件版本與 GitHub Release 資產相符。
41
184
 
42
- ## License
185
+ ## 授權與致謝
43
186
 
44
- MIT; see [LICENSE](LICENSE) for the original copyright notice.
187
+ 本專案採用 [MIT License](LICENSE)。原始專案由 owntag 建立;保留原始版權聲明:Copyright (c) 2026 owntag。使用、修改或散布時請遵守授權條款並保留所需的版權與授權聲明。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dac-tech-team-tw/gtm-cli",
3
- "version": "1.6.2",
3
+ "version": "1.7.1",
4
4
  "description": "Command-line interface for Google Tag Manager",
5
5
  "keywords": [
6
6
  "google-tag-manager",