@aiusage/cli 1.4.3 → 1.5.0

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.
package/README.md CHANGED
@@ -3,7 +3,8 @@
3
3
  `@aiusage/cli` is the AIUsage command-line tool for:
4
4
 
5
5
  - discovering and managing projects across AI tools
6
- - scanning local Claude Code, Codex, Copilot CLI, and Gemini CLI token usage
6
+ - scanning local Claude Code, Codex, Cursor, Copilot CLI, Copilot for VS Code, Gemini CLI, and Antigravity usage
7
+ - importing historical usage from Anthropic Admin API
7
8
  - printing local usage summaries for the last 7 days, 30 days, 90 days, or all history
8
9
  - scheduling automatic sync to an AIUsage Worker
9
10
  - diagnosing configuration and connectivity issues
@@ -40,7 +41,7 @@ aiusage project alias # list all configured aliases
40
41
  aiusage project alias --remove myapp # remove alias
41
42
  ```
42
43
 
43
- Scans data directories for Claude Code, Codex, Copilot CLI, and Gemini CLI, listing discovered projects with their aliases and sources.
44
+ Scans data directories for Claude Code, Codex, Cursor, Copilot CLI, Copilot for VS Code, Gemini CLI, and Antigravity, listing discovered projects with their aliases and sources.
44
45
 
45
46
  Project aliases are applied locally before upload. If two devices set the same alias for their respective project directories, the server merges them into one project.
46
47
 
@@ -59,7 +60,7 @@ aiusage report --no-emoji # disable emoji in title
59
60
  aiusage report --json # JSON output
60
61
  ```
61
62
 
62
- Reads data from `~/.claude/projects` (Claude Code) and `~/.codex` (Codex).
63
+ Reads data from local tool data directories including `~/.claude/projects` (Claude Code), `~/.codex` (Codex), Cursor local state plus usage export, VS Code Copilot Chat logs, and `~/.gemini/antigravity` (Antigravity).
63
64
 
64
65
  **Compact mode** (default) shows Sources and Daily tables with merged Cache column and 2-decimal cost. **Detail mode** (`--detail`) expands all columns (CacheRead, CacheWrite, Reasoning), adds Top Models and Pricing Notes sections, and shows 4-decimal cost.
65
66
 
@@ -104,16 +105,36 @@ aiusage enroll \
104
105
 
105
106
  ### sync
106
107
 
107
- Upload usage data to the Worker. Covers the last 7 closed days by default.
108
+ Upload usage data to the Worker. Default: last 7 days + today.
108
109
 
109
110
  ```bash
110
- aiusage sync
111
- aiusage sync --today # include today's live data
112
- aiusage sync --date 2026-03-31
113
- aiusage sync --lookback 14
111
+ aiusage sync # last 7 days + today
112
+ aiusage sync --today # today only
113
+ aiusage sync --date 2026-03-31 # specific date
114
+ aiusage sync --lookback 14 # last 14 days + today
115
+ aiusage sync --from 2025-01-01 --to 2026-04-05 # date range
114
116
  ```
115
117
 
116
- Use `--today` to upload the current (incomplete) day. The server upserts, so partial data is updated on next sync.
118
+ The server upserts, so re-syncing the same dates safely updates existing data.
119
+
120
+ ### import
121
+
122
+ Import historical Claude usage from the Anthropic Admin API. Useful for recovering data from periods where local JSONL logs were rotated or deleted.
123
+
124
+ ```bash
125
+ aiusage import --start 2025-06-01 --end 2025-09-15
126
+ aiusage import --key sk-ant-admin... --start 2025-06-01 --end 2025-09-15
127
+ ```
128
+
129
+ Requires an **Admin API key** (`sk-ant-admin...`), not a regular API key. Get one at [console.anthropic.com](https://console.anthropic.com) → Settings → Admin Keys.
130
+
131
+ Save the key once:
132
+
133
+ ```bash
134
+ aiusage config set anthropic-admin-key sk-ant-admin...
135
+ ```
136
+
137
+ **Important:** Do not use `import` for dates already covered by local scan data — it will double-count.
117
138
 
118
139
  ### schedule
119
140
 
@@ -144,9 +165,17 @@ Manage local settings.
144
165
  ```bash
145
166
  aiusage config set lang zh # default language: en or zh
146
167
  aiusage config set emoji false # disable emoji in report title
147
- aiusage config set device.alias "MacBook Pro 工作机"
148
- aiusage config set privacy.projectVisibility masked
149
- aiusage config set project.alias MyApp "我的应用" # prefer: aiusage project alias
168
+ aiusage config set device.alias "MacBook Pro 工作机" # device display name on dashboard
169
+ aiusage config set privacy.projectVisibility masked # hidden | masked | plain
170
+ aiusage config set project.alias MyApp "我的应用" # prefer: aiusage project alias
171
+ aiusage config set anthropic-admin-key sk-ant-admin... # for aiusage import
172
+ ```
173
+
174
+ **Device alias** is shown on the dashboard to distinguish multiple devices. Set it to something recognizable (e.g. your machine name or emoji):
175
+
176
+ ```bash
177
+ aiusage config set device.alias "💻 MacBook Pro"
178
+ aiusage config set device.alias "🖥️ iMac Studio"
150
179
  ```
151
180
 
152
181
  CLI flags (`--lang`, `--no-emoji`) override config values for a single run.
package/README.zh-CN.md CHANGED
@@ -2,7 +2,9 @@
2
2
 
3
3
  `@aiusage/cli` 是 AIUsage 命令行工具,用于:
4
4
 
5
- - 扫描本地 AI 编程工具的 Token 用量(Claude Code、Codex、Copilot CLI、Gemini CLI、Qwen Code、Kimi Code、Amp、Droid、OpenCode、Pi)
5
+ - 发现和管理本机 AI 工具项目
6
+ - 扫描本地 AI 编程工具的 Token 用量(Claude Code、Codex、Copilot CLI、Gemini CLI 等)
7
+ - 通过 Anthropic Admin API 导入历史用量
6
8
  - 生成本地用量报告(最近 7 天、30 天、90 天或全部历史)
7
9
  - 定时自动同步数据到 AIUsage Worker
8
10
  - 诊断配置与连接问题
@@ -27,6 +29,22 @@ aiusage --help
27
29
 
28
30
  ## 命令
29
31
 
32
+ ### project
33
+
34
+ 发现和管理本机项目。
35
+
36
+ ```bash
37
+ aiusage project # 列出所有发现的项目(默认)
38
+ aiusage project list # 同上
39
+ aiusage project alias myapp "我的应用" # 设置项目别名
40
+ aiusage project alias # 查看所有已配置的别名
41
+ aiusage project alias --remove myapp # 移除别名
42
+ ```
43
+
44
+ 扫描 Claude Code、Codex、Copilot CLI、Gemini CLI 的数据目录,列出发现的项目及其别名和来源。
45
+
46
+ 项目别名在上传前本地解析。两台设备对各自项目目录设置相同的别名,服务端会将其合并为一个项目。
47
+
30
48
  ### report
31
49
 
32
50
  本地用量报告,无需服务端。
@@ -55,6 +73,39 @@ aiusage scan --date 2026-03-31 --json
55
73
 
56
74
  省略 `--date` 时默认扫描昨天。
57
75
 
76
+ ### sync
77
+
78
+ 上传用量数据到 Worker。默认:最近 7 天 + 今天。
79
+
80
+ ```bash
81
+ aiusage sync # 最近 7 天 + 今天
82
+ aiusage sync --today # 仅今天
83
+ aiusage sync --date 2026-03-31 # 指定日期
84
+ aiusage sync --lookback 14 # 最近 14 天 + 今天
85
+ aiusage sync --from 2025-01-01 --to 2026-04-05 # 指定日期范围
86
+ ```
87
+
88
+ 服务端使用 upsert,重复同步相同日期会安全更新已有数据。
89
+
90
+ ### import
91
+
92
+ 通过 Anthropic Admin API 导入历史 Claude 用量。适用于本地 JSONL 日志已被清理或删除的时间段。
93
+
94
+ ```bash
95
+ aiusage import --start 2025-06-01 --end 2025-09-15
96
+ aiusage import --key sk-ant-admin... --start 2025-06-01 --end 2025-09-15
97
+ ```
98
+
99
+ 需要 **Admin API 密钥**(`sk-ant-admin...`),而非普通 API 密钥。前往 [console.anthropic.com](https://console.anthropic.com) → Settings → Admin Keys 获取。
100
+
101
+ 保存密钥(一次性):
102
+
103
+ ```bash
104
+ aiusage config set anthropic-admin-key sk-ant-admin...
105
+ ```
106
+
107
+ **注意:** 不要对已有本地扫描数据的日期使用 `import`,否则会重复计数。
108
+
58
109
  ### init
59
110
 
60
111
  初始化本地配置。
@@ -83,19 +134,6 @@ aiusage enroll \
83
134
  --device-name "MacBook Pro"
84
135
  ```
85
136
 
86
- ### sync
87
-
88
- 上传用量数据到 Worker。默认覆盖最近 7 个已结束的日期。
89
-
90
- ```bash
91
- aiusage sync
92
- aiusage sync --today # 包含今日实时数据
93
- aiusage sync --date 2026-03-31
94
- aiusage sync --lookback 14
95
- ```
96
-
97
- 使用 `--today` 上传当日(未完成)数据。服务端使用 upsert,部分数据会在下次同步时更新。
98
-
99
137
  ### schedule
100
138
 
101
139
  管理定时同步。macOS 使用 `launchd`,Linux 使用 `cron`。
@@ -104,21 +142,10 @@ aiusage sync --lookback 14
104
142
  aiusage schedule on # 启用,默认每 5 分钟
105
143
  aiusage schedule on --every 30m # 自定义间隔
106
144
  aiusage schedule off # 关闭
107
- aiusage schedule status # 查看当前定时任务详情
145
+ aiusage schedule status # 查看当前状态
108
146
  ```
109
147
 
110
- 支持间隔:`5m` – `1d`。定时同步始终包含今日实时数据(`--today`),确保看板数据及时更新。
111
-
112
- `schedule status` 输出示例:
113
-
114
- ```
115
- 状态: 已启用
116
- 间隔: 每 5m
117
- 含今日: 是
118
- 命令: /usr/local/bin/node /usr/local/bin/aiusage sync --today
119
- 配置: ~/Library/LaunchAgents/com.aiusage.sync.plist
120
- 日志: ~/.aiusage/sync.log
121
- ```
148
+ 支持间隔:`5m` – `1d`。定时同步始终包含今日实时数据,确保看板数据及时更新。
122
149
 
123
150
  ### doctor
124
151
 
@@ -135,9 +162,17 @@ aiusage doctor
135
162
  ```bash
136
163
  aiusage config set lang zh # 默认语言: en 或 zh
137
164
  aiusage config set emoji false # 禁用报告标题 emoji
138
- aiusage config set device.alias "MacBook Pro 工作机"
139
- aiusage config set privacy.projectVisibility masked
140
- aiusage config set project.alias /Users/me/Projects/MyApp MyApp
165
+ aiusage config set device.alias "MacBook Pro 工作机" # Dashboard 上显示的设备名称
166
+ aiusage config set privacy.projectVisibility masked # hidden | masked | plain
167
+ aiusage config set project.alias MyApp "我的应用" # 推荐用 aiusage project alias
168
+ aiusage config set anthropic-admin-key sk-ant-admin... # 用于 aiusage import
169
+ ```
170
+
171
+ **设备别名**会在 Dashboard 上显示,用于区分多台设备。建议设置为容易辨认的名称:
172
+
173
+ ```bash
174
+ aiusage config set device.alias "💻 MacBook Pro"
175
+ aiusage config set device.alias "🖥️ iMac Studio"
141
176
  ```
142
177
 
143
178
  CLI 标志(`--lang`、`--no-emoji`)会覆盖配置值(仅当次生效)。