cchistory-cli
GitHub提供 CCHistory CLI 的完整操作指南，涵盖数据发现、同步、项目/会话查询、导出导入及备份验证。按只读、预览和变更三级安全分层组织命令，支持 JSON 输出与本地存储管理。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill cchistory-cli -g -y
SKILL.md
Frontmatter
{
"name": "cchistory-cli",
"description": "Operate the CCHistory CLI — discover sources, sync, query projects\/turns\/sessions, export\/import\/backup bundles, and verify restores. Use when the user wants to interact with CCHistory data through the local CLI. Covers all read, preview, and mutating workflows with safety-tiered command guidance."
}
CCHistory CLI
This skill covers the full CCHistory CLI surface. Commands are organized by safety tier: read-only first, preview-first second, mutating last.
Transport
Preferred command forms:
- Installed CLI:
cchistory ... - Repo checkout fallback:
node apps/cli/dist/index.js ...(build first withpnpm --filter @cchistory/cli build)
Always add --json for machine-readable output. Read commands should default to
--index unless the user explicitly wants --full (re-scan from source roots).
Store targeting: --store <dir> or --db <file>.
Tier 1 — Read-Only
These commands never mutate the store.
Source & store inspection
cchistory discover --json # what sources exist on this host
cchistory discover --showall --json # include missing candidates
cchistory ls sources --index --json # indexed source inventory
cchistory ls projects --index --json # project listing
cchistory ls sessions --index --json # session listing
cchistory stats --index --json # store summary counts
cchistory stats usage --by model --index --json # token usage breakdown (model|project|source|host|day|month)
Project drill-down
cchistory query projects --index --json # project inventory
cchistory query project --id <project-id> --index --json # one project + linked turns
cchistory query turns --project <id> --limit <n> --index --json # filtered turn list
cchistory query turns --project <id> --search <q> --index --json # project-scoped search
Use --link-state committed|candidate|unlinked|all to filter linkage.
Turn & session drill-down
cchistory query turn --id <turn-id> --index --json # one turn + context + lineage
cchistory query session --id <session-ref> --index --json # one session + turns
Session refs accept: exact ID, unique ID prefix, exact title, or normalized workspace path.
Search
cchistory search <query> --index --json
cchistory search <query> --project <id> --source <id> --limit <n> --index --json
Tree views (human-readable)
cchistory tree projects --index --json
cchistory tree project <id-or-slug> --index --json
cchistory tree session <session-ref> --index --json
Post-import verification
cchistory restore-check --store <dir> --json
cchistory restore-check --db <file> --json
cchistory restore-check --store <dir> --showall --json # include zero-token turns
Tier 2 — Preview (dry-run)
These commands show what a mutation would do without writing anything.
cchistory sync --dry-run --json # sync preview
cchistory sync --dry-run --source <slot-or-id> --json # scoped sync preview
cchistory export --out <dir> --dry-run --json # export preview
cchistory export --out <dir> --source <id> --no-raw --dry-run --json
cchistory backup --out <dir> --json # backup preview (default is preview)
cchistory backup --out <dir> --source <id> --no-raw --json
cchistory import <bundle-dir> --dry-run --json # import preview
cchistory import <bundle-dir> --on-conflict skip --dry-run --json
cchistory gc --dry-run --json # garbage collection preview
Always run the Tier 2 preview before executing the corresponding Tier 3 command. Show the preview result to the user and get confirmation.
Tier 3 — Mutating
These commands write to the store or filesystem. Only run after the user has seen and confirmed the Tier 2 preview.
cchistory sync --json # real sync
cchistory sync --source <slot-or-id> --json
cchistory export --out <dir> --json # write export bundle
cchistory backup --out <dir> --write --json # write backup bundle
cchistory import <bundle-dir> --json # execute import
cchistory import <bundle-dir> --on-conflict skip --json
cchistory gc --json # execute garbage collection
Carry forward the same scope flags (--store, --db, --source, --no-raw,
--on-conflict) used in the preview.
Rules
- Do not start API or web services. This skill uses CLI only.
- Default to
--indexfor reads; only use--fullwhen user explicitly accepts a rescan. - Always preview before mutating.
- Preserve canonical CLI JSON field names; do not invent skill-local schemas.
- Use domain terms exactly: project, turn, session, source, bundle, blob, context, lineage, store.
- Surface CLI errors directly; do not silently retry with a different command.
Version History
- e0220ca Current 2026-07-05 21:39
