Analyticscli CLI

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

Supported Versions

• Skill pack: 1.0.7
• Target package: @analyticscli/cli
• Supported range: >=0.1.3 <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.

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.

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.

Error Recovery Order

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

1. Refetch this skill and update the CLI first.
2. Rerun the exact failing command or smallest reproducible command.
3. 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:

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli || npm install -g --prefix "$HOME/.local" @analyticscli/cli
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.

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.

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:

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

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.

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:

npm install -g @analyticscli/cli
command -v analyticscli
npx -y @analyticscli/cli setup
# Paste readonly token only when prompted; do not pass token as a command argument.

Alternatives:

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.

npm install -g @analyticscli/cli
analyticscli --help

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

mkdir -p "$HOME/.local"
npm install -g --prefix "$HOME/.local" @analyticscli/cli
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:

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

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

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.

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.

Validation Loop

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

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.

Missing Capability Loop

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

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

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

References

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