cxs is a local-first CLI for searching Codex session logs. It is designed for progressive retrieval: find the right session first, then read
feat(release): GH Actions binary matrix + 一行 install.sh + README rework
提供给最终用户的零依赖安装路径:
- .github/workflows/release.yml: tag push v* 或手动 workflow_dispatch
触发,matrix 5 平台 (darwin-arm64/x64 / linux-x64/arm64 / windows-x64),
全在 ubuntu-latest 上用 bun build --compile 跨平台编译,upload 到
release 资产
- scripts/install.sh: 一行 curl ... | bash,自动 detect uname,从
release 拉对应 binary 到 ~/.local/bin/cxs (CXS_INSTALL_DIR 覆盖),
chmod +x 并跑一次 --version 自检;如果 install dir 不在 PATH 主动
提示
- README "CLI Install Guide" 重写:把 binary 一行装放第一位,源码
模式作为 dev/PR 路径放第二;补 CXS_DATA_DIR 数据目录覆盖说明
binary 模式无 Bun/Node 运行时依赖。本地实测 bun build --compile
--target=bun-darwin-arm64 出 58 MB binary,--version / current
schema-error / sync empty / stats 全部跑通。
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Entire-Checkpoint: b17128559666
+173
-17
+94
.github/workflows/release.yml
+94
.github/workflows/release.yml
···
1
+
name: release
2
+
3
+
on:
4
+
push:
5
+
tags:
6
+
- "v*"
7
+
workflow_dispatch:
8
+
inputs:
9
+
tag:
10
+
description: "Release tag (e.g. v0.1.0). Required when triggered manually."
11
+
required: true
12
+
13
+
permissions:
14
+
contents: write
15
+
16
+
jobs:
17
+
build:
18
+
name: build ${{ matrix.target }}
19
+
runs-on: ubuntu-latest
20
+
strategy:
21
+
fail-fast: false
22
+
matrix:
23
+
include:
24
+
- target: bun-darwin-arm64
25
+
asset: cxs-darwin-arm64
26
+
- target: bun-darwin-x64
27
+
asset: cxs-darwin-x64
28
+
- target: bun-linux-x64
29
+
asset: cxs-linux-x64
30
+
- target: bun-linux-arm64
31
+
asset: cxs-linux-arm64
32
+
- target: bun-windows-x64
33
+
asset: cxs-windows-x64.exe
34
+
steps:
35
+
- name: Checkout
36
+
uses: actions/checkout@v4
37
+
38
+
- name: Setup Bun
39
+
uses: oven-sh/setup-bun@v2
40
+
with:
41
+
bun-version: latest
42
+
43
+
- name: Install dependencies
44
+
run: bun install --frozen-lockfile
45
+
46
+
- name: Build standalone binary
47
+
run: |
48
+
mkdir -p dist
49
+
bun build ./cli.ts \
50
+
--compile \
51
+
--target=${{ matrix.target }} \
52
+
--outfile dist/${{ matrix.asset }}
53
+
54
+
- name: Upload artifact
55
+
uses: actions/upload-artifact@v4
56
+
with:
57
+
name: ${{ matrix.asset }}
58
+
path: dist/${{ matrix.asset }}
59
+
if-no-files-found: error
60
+
61
+
release:
62
+
name: publish release
63
+
needs: build
64
+
runs-on: ubuntu-latest
65
+
steps:
66
+
- name: Checkout
67
+
uses: actions/checkout@v4
68
+
69
+
- name: Resolve tag
70
+
id: tag
71
+
run: |
72
+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
73
+
echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
74
+
else
75
+
echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
76
+
fi
77
+
78
+
- name: Download all artifacts
79
+
uses: actions/download-artifact@v4
80
+
with:
81
+
path: dist
82
+
merge-multiple: true
83
+
84
+
- name: List artifacts
85
+
run: ls -la dist
86
+
87
+
- name: Create or update release
88
+
uses: softprops/action-gh-release@v2
89
+
with:
90
+
tag_name: ${{ steps.tag.outputs.tag }}
91
+
name: ${{ steps.tag.outputs.tag }}
92
+
generate_release_notes: true
93
+
files: dist/cxs-*
94
+
fail_on_unmatched_files: true
+20
-17
README.md
+20
-17
README.md
···
30
30
- `cxs stats`
31
31
- `cxs current`
32
32
33
-
## 安装
33
+
## CLI Install Guide
34
+
35
+
### 一行安装(推荐:零依赖)
36
+
37
+
从 GitHub Release 拉对应平台的 standalone binary,自动放到 `~/.local/bin/cxs`,**不需要预装 Bun 或 Node**:
34
38
35
39
```bash
36
-
bun install
40
+
curl -fsSL https://raw.githubusercontent.com/catoncat/cxs/main/scripts/install.sh | bash
37
41
```
38
42
39
-
## CLI Install Guide
43
+
支持平台:darwin-arm64 / darwin-x64 / linux-x64 / linux-arm64 / windows-x64。如果 `~/.local/bin` 不在 PATH,脚本会提示;或先 `export CXS_INSTALL_DIR=/usr/local/bin` 再跑。
40
44
41
-
`cxs` 目前推荐从源码安装，适合本机工具或 agent sidecar 使用：
45
+
### 从源码(开发者 / 需要 PR / Bun 路线)
42
46
43
47
```bash
44
48
git clone https://github.com/catoncat/cxs.git
···
49
53
"$CXS_BIN" --help
50
54
```
51
55
52
-
`--version` 应输出当前 `package.json` 里的版本号；`--help` 应显示 `sync`、`find`、`read-range`、`read-page`、`list`、`stats`、`current`。
56
+
`--help` 应列出 `sync` / `find` / `read-range` / `read-page` / `list` / `stats` / `current`。
53
57
54
-
首次使用前建立索引：
58
+
### 首次使用建立索引
55
59
56
60
```bash
57
-
"$CXS_BIN" sync
58
-
"$CXS_BIN" stats --json
61
+
cxs sync # 装的是 standalone binary
62
+
# 或 "$CXS_BIN" sync # 装的是源码模式
63
+
cxs stats --json
59
64
```
60
65
61
-
如果希望直接使用 `cxs` 命令，可以把仓库里的启动脚本链接到 PATH：
66
+
### 数据目录
67
+
68
+
索引默认写到 `~/.cache/cxs/index.sqlite`(XDG cache 约定),可用 `CXS_DATA_DIR` 环境变量覆盖:
62
69
63
70
```bash
64
-
mkdir -p ~/bin
65
-
ln -sf "$PWD/bin/cxs" ~/bin/cxs
66
-
export PATH="$HOME/bin:$PATH"
67
-
cxs --version
71
+
export CXS_DATA_DIR="$HOME/.config/cxs"
68
72
```
69
73
70
-
要求：
74
+
### 要求
71
75
72
-
- Bun `>= 1.3`
73
-
- 本机可读取 `~/.codex/sessions`
74
-
- 默认会在仓库内使用 `./data/index.sqlite` 作为索引库
76
+
- 本机可读 `~/.codex/sessions`
77
+
- 源码模式需 Bun `>= 1.3`;binary 模式无运行时依赖
75
78
76
79
## 用法
77
80
+59
scripts/install.sh
+59
scripts/install.sh
···
1
+
#!/usr/bin/env bash
2
+
# Install the cxs CLI from a GitHub Release binary.
3
+
#
4
+
# Usage:
5
+
# curl -fsSL https://raw.githubusercontent.com/catoncat/cxs/main/scripts/install.sh | bash
6
+
#
7
+
# Override the destination with CXS_INSTALL_DIR (default: ~/.local/bin).
8
+
9
+
set -euo pipefail
10
+
11
+
OWNER="catoncat"
12
+
REPO="cxs"
13
+
INSTALL_DIR="${CXS_INSTALL_DIR:-$HOME/.local/bin}"
14
+
15
+
OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
16
+
ARCH_RAW="$(uname -m)"
17
+
18
+
case "$ARCH_RAW" in
19
+
arm64|aarch64) ARCH="arm64" ;;
20
+
x86_64|amd64) ARCH="x64" ;;
21
+
*) echo "unsupported arch: $ARCH_RAW" >&2; exit 1 ;;
22
+
esac
23
+
24
+
case "$OS" in
25
+
darwin) EXT=""; PLATFORM="darwin-$ARCH" ;;
26
+
linux) EXT=""; PLATFORM="linux-$ARCH" ;;
27
+
msys*|cygwin*|mingw*) EXT=".exe"; PLATFORM="windows-$ARCH" ;;
28
+
*) echo "unsupported os: $OS" >&2; exit 1 ;;
29
+
esac
30
+
31
+
ASSET="cxs-${PLATFORM}${EXT}"
32
+
URL="https://github.com/${OWNER}/${REPO}/releases/latest/download/${ASSET}"
33
+
34
+
mkdir -p "$INSTALL_DIR"
35
+
TARGET="$INSTALL_DIR/cxs${EXT}"
36
+
37
+
echo "downloading $ASSET from $URL"
38
+
curl -fsSL --proto '=https' --tlsv1.2 -o "$TARGET" "$URL"
39
+
chmod +x "$TARGET"
40
+
41
+
echo
42
+
echo "installed: $TARGET"
43
+
echo
44
+
"$TARGET" --version || {
45
+
echo "warning: just-installed binary failed to run; remove $TARGET and retry" >&2
46
+
exit 1
47
+
}
48
+
49
+
case ":$PATH:" in
50
+
*":$INSTALL_DIR:"*)
51
+
echo
52
+
echo "ready: cxs --help"
53
+
;;
54
+
*)
55
+
echo
56
+
echo "tip: $INSTALL_DIR is not in PATH yet; add to your shell rc:"
57
+
echo " export PATH=\"$INSTALL_DIR:\$PATH\""
58
+
;;
59
+
esac