analyticscli-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AnalyticsCLI CLI

Use This Skill When

适用场景

querying product analytics for a AnalyticsCLI project
validating whether SDK instrumentation landed correctly
reviewing or submitting project feedback through AnalyticsCLI
answering onboarding, paywall, survey, retention, or export questions without raw SQL

为AnalyticsCLI项目查询产品分析数据
验证SDK埋点是否正确部署
通过AnalyticsCLI查看或提交项目反馈
无需使用原生SQL即可解答新手引导、付费墙、调研、留存或导出相关问题

Supported Versions

支持版本

Skill pack:
```
1.0.5
```
Target package:
```
@analyticscli/cli@preview
```
Supported range:
```
>=0.1.2-preview.0 <0.2.0
```
If a future CLI major changes commands or flags in incompatible ways, split to a sibling skill such as
```
analyticscli-cli-v1
```

See Versioning Notes.

技能包：
```
1.0.5
```
目标包：
```
@analyticscli/cli@preview
```
支持版本范围：
```
>=0.1.2-preview.0 <0.2.0
```
如果未来CLI大版本更新导致命令或参数不兼容，需拆分出同级技能，例如
```
analyticscli-cli-v1
```

查看版本说明。

Non-Goals

不包含目标

Do not generate raw SQL.
Do not request unbounded raw event dumps.
Do not include debug data unless the user explicitly asks for it.

不生成原生SQL。
不请求无限制的原始事件导出。
除非用户明确要求，否则不包含调试数据。

Safety Rules

安全规则

Always scope by project context: set default once with
```
analyticscli projects select
```
, or pass
```
--project <id>
```
when needed.
Always scope by time:
```
--last
```
or explicit
```
since/until
```
.
Prefer high-level query endpoints over raw exports.
Keep groupings and result sets bounded.
Treat release-only data as the default.
Never pass secrets via CLI flags or inline literals (argv/shell history leakage risk). Use interactive prompts instead.
For generated docs or help text, use tenant developer voice (
```
your workspace
```
,
```
your project
```
) and avoid provider-centric wording such as
```
our SaaS
```
.
Keep
```
analyticscli-cli
```
skill fresh with CLI updates, but do not auto-force
```
analyticscli-ts-sdk
```
skill updates across repositories.

始终按项目上下文限定范围：使用
```
analyticscli projects select
```
设置一次默认项目，或在需要时传入
```
--project <id>
```
参数。
始终按时间限定范围：使用
```
--last
```
参数或明确指定
```
since/until
```
时间范围。
优先使用高层级查询端点而非原始导出。
限制分组和结果集的范围。
默认仅使用发布版本的数据。
切勿通过CLI参数或内联字面量传递密钥（存在argv/Shell历史泄露风险），请改用交互式提示。
生成文档或帮助文本时，使用租户开发者视角（如
```
your workspace
```
、
```
your project
```
），避免使用以服务商为中心的表述，例如
```
our SaaS
```
。
随CLI更新保持
```
analyticscli-cli
```
技能的时效性，但不要跨仓库强制更新
```
analyticscli-ts-sdk
```
技能。

Error Recovery Order

错误恢复步骤

When there are problems, errors, unexpected output, or missing CLI/API behavior:

Refetch this skill and update the CLI first.
Rerun the exact failing command or smallest reproducible command.
If no newer version is available, the update fails, or the newest version still has the problem, submit sanitized product feedback to the AnalyticsCLI SaaS owner with
```
analyticscli feedback submit
```
.

Recommended update check:

bash

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli@preview || npm install -g --prefix "$HOME/.local" @analyticscli/cli@preview
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
analyticscli --help

Feedback must include the version/update attempt, failing command or endpoint, sanitized payload shape, status/error body, request id if present, expected behavior, actual behavior, and workaround.

当出现问题、错误、意外输出或CLI/API功能缺失时：

先重新获取此技能并更新CLI。
重新运行完全相同的失败命令或最小可复现命令。
如果没有可用的新版本、更新失败，或最新版本仍存在问题，请使用
```
analyticscli feedback submit
```
向AnalyticsCLI SaaS所有者提交经过脱敏的产品反馈。

推荐的更新检查命令：

bash

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli@preview || npm install -g --prefix "$HOME/.local" @analyticscli/cli@preview
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
analyticscli --help

反馈必须包含版本/更新尝试信息、失败命令或端点、脱敏后的负载结构、状态/错误体（若存在）、请求ID（若存在）、预期行为、实际行为以及临时解决方案。

Query Priorities

查询优先级

Prefer these command families first:

```
funnel
```
```
conversion-after
```
```
paths-after
```
```
retention
```
```
survey
```
```
timeseries
```
```
breakdown
```
```
generic
```

Only use

events export

when the user explicitly needs raw CSV.

优先使用以下命令系列：

```
funnel
```
```
conversion-after
```
```
paths-after
```
```
retention
```
```
survey
```
```
timeseries
```
```
breakdown
```
```
generic
```

仅当用户明确需要原始CSV时，才使用

events export

命令。

Feedback Commands

反馈命令

Use these when the task involves feedback about AnalyticsCLI itself, such as missing features, broken CLI/API/dashboard behavior, confusing errors, poor docs, or workflow friction:

bash

analyticscli feedback list --last 30d --format json
analyticscli feedback summary --last 30d --format json
analyticscli feedback submit --category bug --message "Short symptom" --origin-name "dashboard feedback form" --location-id "dashboard/feedback"

Rules:

do not confuse this with tenant-owned end-user feedback collected by the AnalyticsCLI feedback feature
prefer
```
feedback summary --format json
```
when another tool or skill needs a bounded theme summary
prefer
```
feedback list --format json
```
when exact raw messages matter
always include
```
origin-name
```
and
```
location-id
```
on submit when they are known
for API/CLI failures, first update/refetch the current skill and CLI; if the newest available version still fails, include sanitized endpoint/command, version/update attempt, status code, error body, request id if present, expected behavior, and the workaround used

当任务涉及对AnalyticsCLI本身的反馈时（如功能缺失、CLI/API/仪表盘行为异常、错误提示易混淆、文档质量差或工作流程繁琐），使用以下命令：

bash

analyticscli feedback list --last 30d --format json
analyticscli feedback summary --last 30d --format json
analyticscli feedback submit --category bug --message "Short symptom" --origin-name "dashboard feedback form" --location-id "dashboard/feedback"

规则：

不要将此与AnalyticsCLI反馈功能收集的租户自有终端用户反馈混淆
当其他工具或技能需要受限的主题摘要时，优先使用
```
feedback summary --format json
```
当需要精确的原始消息时，优先使用
```
feedback list --format json
```
提交时若已知
```
origin-name
```
和
```
location-id
```
，请务必包含
对于API/CLI故障，先更新/重新获取当前技能和CLI；若最新可用版本仍失败，请包含脱敏后的端点/命令、版本/更新尝试信息、状态码、错误体、请求ID（若存在）、预期行为以及所使用的临时解决方案

Data Fidelity Rules

数据保真规则

CLI and dashboard both query the API. There is no separate CLI-only analytics source.
Sequence-sensitive and cohort-sensitive queries stay on raw events.
Aggregate-backed reads are acceptable only when the API reports that plan shape.
```
runtimeEnv
```
is auto-attached by the SDK. Do not invent a separate mode field.

CLI和仪表盘均查询同一API，不存在仅CLI可用的独立分析数据源。
对序列敏感和群组敏感的查询需基于原始事件。
仅当API报告该计划结构时，才允许使用聚合支持的读取操作。
```
runtimeEnv
```
由SDK自动附加，请勿自行创建单独的模式字段。

One-Time Setup

一次性设置

Before running setup, collect required values from your dashboard:

Open dash.analyticscli.com and select the target project.
In API Keys, create/copy a
```
readonly_token
```
(CLI token, scope
```
read:queries
```
).
If SDK instrumentation is in scope, copy the publishable ingest API key from the same API Keys page.
Optional: copy
```
project_id
```
for explicit per-command overrides.
Set default project once after login with
```
analyticscli projects select
```
(interactive arrow-key picker).

Preferred:

bash

npm install -g @analyticscli/cli@preview
command -v analyticscli
npx -y @analyticscli/cli@preview setup

运行设置前，请从仪表盘收集所需值：

打开dash.analyticscli.com并选择目标项目。
在API Keys页面，创建/复制一个
```
readonly_token
```
（CLI令牌，权限范围
```
read:queries
```
）。
如果涉及SDK埋点，请从同一API Keys页面复制可发布的采集API密钥。
可选：复制
```
project_id
```
用于按命令显式覆盖默认项目。
登录后使用
```
analyticscli projects select
```
（交互式箭头选择器）设置一次默认项目。

推荐设置方式：

bash

npm install -g @analyticscli/cli@preview
command -v analyticscli
npx -y @analyticscli/cli@preview setup

Paste readonly token only when prompted; do not pass token as a command argument.

仅在提示时粘贴只读令牌；请勿将令牌作为命令参数传递。


Alternatives:

```bash
analyticscli login


替代设置方式：

```bash
analyticscli login

Choose readonly-token interactively; do not put tokens in command args.

交互式选择只读令牌；请勿将令牌放入命令参数中。


If `analyticscli: command not found`, install or update the npm package. The package name is
`@analyticscli/cli`; the binary name is `analyticscli`.

Do not search npm for `analyticscli` or `analyticsscli`.

```bash
npm install -g @analyticscli/cli@preview
analyticscli --help

On VPS hosts where global npm installs are blocked, use a user-local prefix:

bash

mkdir -p "$HOME/.local"
npm install -g --prefix "$HOME/.local" @analyticscli/cli@preview
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
analyticscli --help

Fetching or updating this skill is not enough by itself. After every skill update, also update the npm package and verify the binary:

bash

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli@preview || npm install -g --prefix "$HOME/.local" @analyticscli/cli@preview
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
command -v analyticscli
analyticscli --help

command -v analyticscli

is still empty but a user-local binary exists, update shell profile files yourself before reporting success:

bash

for f in "$HOME/.profile" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.zshrc" "$HOME/.zprofile"; do
  touch "$f"
  grep -Fq 'export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"' "$f" ||
    printf '\n# AnalyticsCLI CLI user-local npm bin\nexport PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"\n' >> "$f"
done
bash -lc 'source "$HOME/.bashrc" 2>/dev/null || true; source "$HOME/.profile" 2>/dev/null || true; command -v analyticscli && analyticscli --help >/dev/null'

Do not say analyticscli is fixed until

command -v analyticscli && analyticscli --help >/dev/null

succeeds in the same command context you control.


若出现`analyticscli: command not found`，请安装或更新npm包。包名为`@analyticscli/cli`；二进制文件名为`analyticscli`。

请勿在npm上搜索`analyticscli`或`analyticsscli`。

```bash
npm install -g @analyticscli/cli@preview
analyticscli --help

在全局npm安装被阻止的VPS主机上，使用用户本地前缀：

bash

mkdir -p "$HOME/.local"
npm install -g --prefix "$HOME/.local" @analyticscli/cli@preview
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
analyticscli --help

仅获取或更新此技能并不足够。每次技能更新后，还需更新npm包并验证二进制文件：

bash

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli@preview || npm install -g --prefix "$HOME/.local" @analyticscli/cli@preview
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
command -v analyticscli
analyticscli --help

若

command -v analyticscli

仍无输出但存在用户本地二进制文件，请自行更新Shell配置文件后再报告成功：

bash

for f in "$HOME/.profile" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.zshrc" "$HOME/.zprofile"; do
  touch "$f"
  grep -Fq 'export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"' "$f" ||
    printf '\n# AnalyticsCLI CLI user-local npm bin\nexport PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"\n' >> "$f"
done
bash -lc 'source "$HOME/.bashrc" 2>/dev/null || true; source "$HOME/.profile" 2>/dev/null || true; command -v analyticscli && analyticscli --help >/dev/null'

只有当

command -v analyticscli && analyticscli --help >/dev/null

在你控制的同一命令环境中执行成功时，才能说明AnalyticsCLI已修复。

Output Mode

输出模式

Prefer
```
--format json
```
for automation or agent reasoning.
Use
```
--format text
```
for short human summaries.
Use
```
timeseries --viz table
```
when exact values matter.
Use
```
timeseries --viz chart
```
or
```
svg
```
when a trend scan is enough.

对于自动化或Agent推理场景，优先使用
```
--format json
```
。
对于简短的人工摘要，使用
```
--format text
```
。
当需要精确值时，使用
```
timeseries --viz table
```
。
当仅需查看趋势时，使用
```
timeseries --viz chart
```
或
```
svg
```
。

Validation Loop

验证流程

After SDK rollout or query changes, validate with a few stable reads:

bash

analyticscli schema events --limit 200
analyticscli goal-completion --start onboarding:start --complete onboarding:complete --last 30d
analyticscli get onboarding-journey --last 30d --format text

SDK部署或查询变更后，通过以下几个稳定读取操作进行验证：

bash

analyticscli schema events --limit 200
analyticscli goal-completion --start onboarding:start --complete onboarding:complete --last 30d
analyticscli get onboarding-journey --last 30d --format text

Empty-State Guidance (Required)

空状态指引（必填）

When a user has no listed projects:

Explain that they need to create their first project before CLI queries can return analytics data.
Direct them to create it in their AnalyticsCLI dashboard (dash.analyticscli.com).

After creation, run

analyticscli projects list

, then set a default with

analyticscli projects select

When a project exists but has no events yet:

Explain that ingestion has not started for that project.
Tell the user to integrate
```
@analyticscli/sdk
```
in their app codebase.
Tell the user to initialize the SDK with the publishable API key from Dashboard -> API Keys.
Tell the user to trigger at least one event and rerun
```
analyticscli schema events --project <id> --last 14d
```
.
If they already integrated SDK, advise widening
```
--last
```
or removing restrictive filters before deeper debugging.

当用户没有列出任何项目时：

说明用户需要先创建第一个项目，CLI查询才能返回分析数据。
引导用户在AnalyticsCLI仪表盘(dash.analyticscli.com)中创建项目。
创建完成后，运行
```
analyticscli projects list
```
，然后使用
```
analyticscli projects select
```
设置默认项目。

当项目已存在但尚无任何事件时：

说明该项目尚未开始数据采集。
告知用户需在应用代码库中集成
```
@analyticscli/sdk
```
。
告知用户需使用仪表盘API Keys页面中的可发布API密钥初始化SDK。
告知用户需触发至少一个事件，然后重新运行
```
analyticscli schema events --project <id> --last 14d
```
。
如果用户已集成SDK，建议扩大
```
--last
```
时间范围或移除限制性过滤器后再进行深入调试。

Missing Capability Loop

缺失功能处理流程

If the requested fetch is impossible with the current CLI surface:

State that the capability is missing.
Do not pretend another command is equivalent if it is not.
Submit CLI feedback with a reproducible gap report to the AnalyticsCLI feedback store.

bash

analyticscli feedback submit \
  --category feature \
  --message "Missing CLI functionality: <short capability>" \
  --origin-name "analyticscli cli" \
  --location-id "analyticscli-cli" \
  --context "Requested fetch: <what user asked>; attempted command: <command>" \
  --meta '{"expected":"<expected output>","actual":"CLI has no command or endpoint"}'

如果当前CLI无法实现用户请求的查询：

说明该功能缺失。
若其他命令无法替代，请勿谎称其等效。
向AnalyticsCLI反馈存储库提交包含可复现差距报告的CLI反馈。

bash

analyticscli feedback submit \
  --category feature \
  --message "Missing CLI functionality: <short capability>" \
  --origin-name "analyticscli cli" \
  --location-id "analyticscli-cli" \
  --context "Requested fetch: <what user asked>; attempted command: <command>" \
  --meta '{"expected":"<expected output>","actual":"CLI has no command or endpoint"}'

Auto Feedback Rule

自动反馈规则

When a user reports broken behavior, unexpected output, or missing functionality, first update/refetch the current skill and CLI and retry the smallest repro. If no newer version is available, the update is blocked, or the newest version still fails, submit one concise

analyticscli feedback submit

report automatically after explaining the issue.

Include:

clear symptom in
```
--message
```
exact failing command or flow in
```
--context
```
expected vs actual behavior in
```
--meta
```
installed version and update attempt in
```
--context
```
or
```
--meta
```

当用户报告行为异常、意外输出或功能缺失时，先更新/重新获取当前技能和CLI，并重试最小可复现场景。如果没有可用的新版本、更新被阻止，或最新版本仍失败，在向用户解释问题后自动提交一份简洁的

analyticscli feedback submit

报告。

报告需包含：

```
--message
```
中明确说明症状
```
--context
```
中包含精确的失败命令或流程
```
--meta
```
中包含预期与实际行为
```
--context
```
或
```
--meta
```
中包含已安装版本和更新尝试信息

References

参考资料

Versioning Notes
Dedicated Events Playbook
Event Placement Playbook
Paywall Journey Playbook
Store Review Playbook
CLI Use Cases Playbook

版本说明
专用事件手册
事件部署手册
付费墙流程手册
商店审核手册
CLI使用场景手册