@voyager-crew/cli 0.1.0 → 0.3.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
@@ -1,6 +1,6 @@
1
1
  <div align="center">
2
- <img src="assets/logo.png" alt="Voyager logo" width="96" height="96">
3
- <h1>voyager</h1>
2
+ <img src="https://raw.githubusercontent.com/voyager-crew/voyager-cli/main/assets/logo.svg" alt="Voyager CLI logo" width="96" height="96">
3
+ <h1>Voyager CLI</h1>
4
4
  <p>Ask ChatGPT from your terminal, or let your coding agent do it,<br>through the ChatGPT you are already signed in to in your browser.</p>
5
5
  <p>
6
6
  <a href="https://www.npmjs.com/package/@voyager-crew/cli"><img src="https://img.shields.io/npm/v/@voyager-crew/cli?style=flat-square" alt="npm version"></a>
@@ -13,28 +13,35 @@
13
13
  voyager ask "Review this design" --attach ./docs/design.md
14
14
  ```
15
15
 
16
- `voyager` hands the prompt to the [Voyager](https://github.com/voyager-crew/voyager) browser
17
- extension, which types it into a ChatGPT tab, waits for the answer and saves it as
18
- `response.md`. Everything stays on your machine: the CLI listens on `127.0.0.1` only, and
19
- ChatGPT sees an ordinary chat from your own browser.
16
+ Voyager CLI is the reference client for the **ChatGPT Local Bridge** in the
17
+ [Voyager](https://github.com/voyager-crew/voyager) browser extension. The bridge lets programs on
18
+ your computer work with ChatGPT on the web: open a chat, send a prompt with files, wait for the
19
+ reply and read it, manage project files. Voyager CLI puts that in your terminal and saves each
20
+ reply as `response.md`. Everything stays on your machine: the CLI listens on `127.0.0.1` only,
21
+ and ChatGPT sees an ordinary chat from your own browser.
22
+ [More about the bridge →](https://voyager.nagi.fun/en/guide/local-bridge)
20
23
 
21
24
  ## Setup
22
25
 
23
- 1. Install the CLI (Node.js 20.3 or later):
26
+ 1. Install Voyager CLI (Node.js 20.3 or later):
24
27
 
25
28
  ```sh
26
29
  npm install -g @voyager-crew/cli
27
30
  ```
28
31
 
29
- 2. Install Voyager in your browser. In its popup, open **Plugins**, turn on
30
- **ChatGPT · Local Bridge** and allow access to chatgpt.com.
32
+ 2. Install the Voyager extension, version 2.1.0 or later:
33
+ [Chrome](https://chromewebstore.google.com/detail/iifacdnjakkhjjiengaffnegbndgingi) ·
34
+ [Edge](https://microsoftedge.microsoft.com/addons/detail/voyager/gibmkggjijalcjinbdhcpklodjkhhlne) ·
35
+ [Firefox](https://addons.mozilla.org/firefox/addon/gemini-voyager/). In its popup, open
36
+ **Plugins**, turn on **ChatGPT · Local Bridge** and allow access to chatgpt.com.
31
37
  3. Pair them once:
32
38
 
33
39
  ```sh
34
40
  voyager pair
35
41
  ```
36
42
 
37
- Enter the eight-character code it prints in the Local Bridge settings in the popup.
43
+ Open the Voyager popup on a ChatGPT tab and enter the eight-character code it prints in the
44
+ Local Bridge settings.
38
45
 
39
46
  ## Asking
40
47
 
@@ -50,6 +57,11 @@ Every ask uses GPT-6 Pro in chat mode unless you pick another effort, and leaves
50
57
  Voyager never switches ChatGPT to Work mode. The reply lands in `~/.voyager/jobs/<id>/output/`,
51
58
  and `--json` prints its path along with the conversation link.
52
59
 
60
+ Files the reply offers (a CSV, a chart, a zip ChatGPT made) are saved beside it in `files/`,
61
+ with `-2`, `-3`… added when a name repeats; `--no-files` leaves them in ChatGPT. A file that
62
+ cannot be downloaded is reported without failing the command, since the reply itself was
63
+ saved: `voyager read <link>` tries again later.
64
+
53
65
  ### Long answers
54
66
 
55
67
  Pro can think for hours. `ask` waits as long as ChatGPT is still working on the reply, and
@@ -74,9 +86,33 @@ voyager project files "Thesis"
74
86
  voyager project remove "Thesis" old-notes.md # immediate and permanent; asks first
75
87
  ```
76
88
 
89
+ ## Google Drive and GitHub
90
+
91
+ ChatGPT's own Google Drive and GitHub apps can read your files directly, with no upload through the page. Connect them in ChatGPT first.
92
+
93
+ ```sh
94
+ voyager ask --drive ./paper.pdf "Summarize the method" # puts it on Drive and links it in the prompt
95
+ voyager ask --repo owner/name "Why does CI fail?" # ChatGPT's GitHub app reads the repository
96
+ ```
97
+
98
+ `--drive` packs like `--attach` but has no 64 MiB limit (files over 20 MiB inside a folder are still left out), and uploads with [rclone](https://rclone.org/drive/):
99
+ set `VOYAGER_DRIVE_REMOTE` (or `"driveRemote"` in `~/.voyager/config.json`) to a folder on a Google Drive
100
+ remote, such as `gdrive:Voyager`, on the same Google account ChatGPT's Drive app uses. The files stay there.
101
+
102
+ `--repo` asks ChatGPT to commit only to a new `chatgpt/*` branch, so you review before merging. That is a request, not
103
+ a restriction: the app writes wherever its GitHub installation allows, without asking. If it cannot reach the
104
+ repository, voyager stops with exit code 3; add the repository at
105
+ [github.com/settings/installations](https://github.com/settings/installations).
106
+
77
107
  ## Using it from an agent
78
108
 
79
- Claude Code, Codex and any other agent that can run shell commands can use `voyager`.
109
+ Claude Code, Codex and any other agent that can run shell commands can use Voyager CLI. Install
110
+ the skill that teaches them how:
111
+
112
+ ```sh
113
+ npx skills add voyager-crew/voyager-cli
114
+ ```
115
+
80
116
  [`skills/voyager/SKILL.md`](skills/voyager/SKILL.md) is written for them: JSON output, what each
81
117
  exit code means, how to wait for a long job without sending the prompt twice, and how to follow
82
118
  up with `--chat` and the conversation id it got rather than `--continue`.
@@ -86,12 +122,30 @@ One job runs at a time. Every result also names your ChatGPT plan (`Pro Lite ($1
86
122
 
87
123
  ## Good to know
88
124
 
89
- - The bridge opens its own ChatGPT tab and closes it when done. If ChatGPT asks you to sign
90
- in or solve a challenge, `voyager` stops and says so (exit 3); it never works around it.
125
+ - `ask`, `read` and every `project` command open their own ChatGPT tab and close it when they
126
+ end, also after a failure; pass `--keep-tab` to leave it open. If ChatGPT asks you to sign in
127
+ or solve a challenge, Voyager CLI stops, leaves that tab open and says so (exit 3); it never
128
+ works around it.
129
+ - `voyager update` updates everything it can: the CLI (when npm installed it globally),
130
+ `voyager serve` (restarted unless a job is running) and the extension's page data, fetched now
131
+ instead of at its next check. Your browser's store updates the extension itself.
91
132
  - Commands: `voyager --help`. State lives in `~/.voyager` (or `$VOYAGER_HOME`), private to
92
133
  your user.
93
134
  - Tested in Chrome. Edge and Firefox builds of Voyager include the bridge too; Safari does not.
94
135
 
136
+ ## Disclaimer
137
+
138
+ - Voyager and Voyager CLI are community open-source projects. They are not affiliated with or
139
+ endorsed by OpenAI.
140
+ - The bridge automates ChatGPT on the web in your own signed-in browser. OpenAI's
141
+ [Terms of Use](https://openai.com/policies/terms-of-use/) restrict extracting output by automated or programmatic means, so decide
142
+ for yourself whether your use complies before you rely on it. Any limits placed on your account
143
+ as a result are your own risk.
144
+ - Similar tools take the same line: [oracle](https://github.com/steipete/oracle), for example, makes its browser mode an opt-in
145
+ experimental feature and points people who want to avoid the risk to the API. If you need a
146
+ supported route, use the OpenAI API.
147
+ - The bridge is for your own convenience on your own computer: connect only your own account, do not use it to serve other people, share an account or resell usage, and use it only for lawful purposes.
148
+
95
149
  ## License
96
150
 
97
151
  MIT. Development notes are in [CONTRIBUTING.md](CONTRIBUTING.md).
package/README_ZH.md CHANGED
@@ -1,6 +1,6 @@
1
1
  <div align="center">
2
- <img src="assets/logo.png" alt="Voyager logo" width="96" height="96">
3
- <h1>voyager</h1>
2
+ <img src="https://raw.githubusercontent.com/voyager-crew/voyager-cli/main/assets/logo.svg" alt="Voyager CLI logo" width="96" height="96">
3
+ <h1>Voyager CLI</h1>
4
4
  <p>在终端里向 ChatGPT 提问,或者交给你的 coding agent 去问,<br>用的就是你浏览器里已经登录的那个 ChatGPT。</p>
5
5
  <p>
6
6
  <a href="https://www.npmjs.com/package/@voyager-crew/cli"><img src="https://img.shields.io/npm/v/@voyager-crew/cli?style=flat-square" alt="npm version"></a>
@@ -13,27 +13,31 @@
13
13
  voyager ask "帮我审一下这份设计" --attach ./docs/design.md
14
14
  ```
15
15
 
16
- `voyager` 把问题交给 [Voyager](https://github.com/voyager-crew/voyager) 浏览器插件。插件在
17
- ChatGPT 标签页里填好问题、等它回答完,再把回答存成 `response.md`。全程都在你自己的电脑上:命令行只监听
18
- `127.0.0.1`,ChatGPT 看到的就是你浏览器里一次普通的对话。
16
+ Voyager CLI 是 [Voyager](https://github.com/voyager-crew/voyager) 浏览器插件里 **ChatGPT 本地桥**
17
+ 的参考客户端。本地桥让本机程序可以跟 ChatGPT 网页版协作:打开对话、附文件发送、等回复写完再读取、管理项目文件。Voyager CLI
18
+ 把这些带到终端里,每次的回答存成 `response.md`。全程都在你自己的电脑上:命令行只监听 `127.0.0.1`,ChatGPT
19
+ 看到的就是你浏览器里一次普通的对话。[了解本地桥 →](https://voyager.nagi.fun/guide/local-bridge)
19
20
 
20
21
  ## 安装
21
22
 
22
- 1. 安装命令行(需要 Node.js 20.3 或更高版本):
23
+ 1. 安装 Voyager CLI(需要 Node.js 20.3 或更高版本):
23
24
 
24
25
  ```sh
25
26
  npm install -g @voyager-crew/cli
26
27
  ```
27
28
 
28
- 2. 在浏览器里安装 Voyager。打开插件弹窗,进入 **插件**,打开 **ChatGPT · 本地桥**,并允许访问
29
- chatgpt.com。
29
+ 2. 安装 Voyager 插件,需要 2.1.0 或更高版本:
30
+ [Chrome](https://chromewebstore.google.com/detail/iifacdnjakkhjjiengaffnegbndgingi) ·
31
+ [Edge](https://microsoftedge.microsoft.com/addons/detail/voyager/gibmkggjijalcjinbdhcpklodjkhhlne) ·
32
+ [Firefox](https://addons.mozilla.org/firefox/addon/gemini-voyager/)。打开插件弹窗,进入
33
+ **插件**,打开 **ChatGPT · 本地桥**,并允许访问 chatgpt.com。
30
34
  3. 配对一次:
31
35
 
32
36
  ```sh
33
37
  voyager pair
34
38
  ```
35
39
 
36
- 把它显示的 8 位配对码填进弹窗里「本地桥」的设置。
40
+ 在 ChatGPT 标签页上打开 Voyager 弹窗,把它显示的 8 位配对码填进「本地桥接」的设置。
37
41
 
38
42
  ## 提问
39
43
 
@@ -48,6 +52,10 @@ voyager read <链接|id> # 保存某个对话的最
48
52
  默认用聊天模式下的 GPT-6 Pro,除非你另选思考强度;问完保持在这个选择上。Voyager 不会把 ChatGPT
49
53
  切到「工作」模式。回答保存在 `~/.voyager/jobs/<id>/output/`,加 `--json` 会输出文件路径和对话链接。
50
54
 
55
+ 回答里给出的文件(ChatGPT 生成的 CSV、图表、zip 等)会存到旁边的 `files/` 里,重名的依次加 `-2`、`-3`;
56
+ 加 `--no-files` 就不下载。某个文件下载失败只会报告,不会让命令失败,因为回答本身已经保存:之后可以用
57
+ `voyager read <链接>` 再取一次。
58
+
51
59
  ### 很长的回答
52
60
 
53
61
  Pro 可能要想好几个小时。只要 ChatGPT 还在写,`ask` 就一直等;连续 20 分钟完全没动静才算失败。想先拿回终端,就先提交、之后再取:
@@ -69,9 +77,31 @@ voyager project files "论文"
69
77
  voyager project remove "论文" old-notes.md # 立即删除且无法恢复,会先确认
70
78
  ```
71
79
 
80
+ ## Google Drive 和 GitHub
81
+
82
+ ChatGPT 自带的 Google Drive 和 GitHub 应用可以直接读你的文件,不用再经过网页上传。先在 ChatGPT 里连上它们。
83
+
84
+ ```sh
85
+ voyager ask --drive ./paper.pdf "总结一下方法部分" # 放到 Drive 上,把链接写进提示
86
+ voyager ask --repo owner/name "CI 为什么挂了?" # 让 ChatGPT 的 GitHub 应用读这个仓库
87
+ ```
88
+
89
+ `--drive` 的打包方式和 `--attach` 一样,但没有 64 MiB 的限制(文件夹里超过 20 MiB 的单个文件仍会被跳过),用 [rclone](https://rclone.org/drive/) 上传:
90
+ 把 `VOYAGER_DRIVE_REMOTE`(或 `~/.voyager/config.json` 里的 `"driveRemote"`)设成某个 Google Drive remote 上的文件夹,
91
+ 比如 `gdrive:Voyager`,而且要和 ChatGPT 的 Drive 应用是同一个 Google 账号。文件会一直留在那里。
92
+
93
+ `--repo` 会要求 ChatGPT 只往一个新的 `chatgpt/*` 分支提交,你看过再合并。这只是要求,不是限制:它的 GitHub
94
+ 安装能写到哪里,它就能写到哪里,而且不会先问你。读不到仓库时,voyager 以退出码 3 停下,去
95
+ [github.com/settings/installations](https://github.com/settings/installations) 把仓库加上就行。
96
+
72
97
  ## 给 agent 用
73
98
 
74
- Claude Code、Codex 以及任何能运行终端命令的 agent 都能用 `voyager`。
99
+ Claude Code、Codex 以及任何能运行终端命令的 agent 都能用 Voyager CLI。先装上教它们怎么用的 skill:
100
+
101
+ ```sh
102
+ npx skills add voyager-crew/voyager-cli
103
+ ```
104
+
75
105
  [`skills/voyager/SKILL.md`](skills/voyager/SKILL.md) 就是写给它们看的:JSON 输出、每个退出码的含义、怎么等长任务而不把问题发两遍,以及接着问时用
76
106
  `--chat` 加上次拿到的对话 id,而不是 `--continue`。
77
107
 
@@ -80,11 +110,22 @@ Claude Code、Codex 以及任何能运行终端命令的 agent 都能用 `voyage
80
110
 
81
111
  ## 须知
82
112
 
83
- - 桥会自己打开一个 ChatGPT 标签页,用完关掉。如果 ChatGPT 要求登录或人机验证,`voyager`
84
- 会停下来告诉你(退出码 3),不会绕过。
113
+ - `ask`、`read` 和所有 `project` 命令都会自己打开一个 ChatGPT 标签页,结束时关掉,失败了也关;
114
+ 想留着就加 `--keep-tab`。如果 ChatGPT 要求登录或人机验证,Voyager CLI 会停下来、留着那个
115
+ 标签页并告诉你(退出码 3),不会绕过。
116
+ - `voyager update` 把能更新的都更新一遍:命令行本身(用 npm 全局安装时)、`voyager serve`
117
+ (没有任务在跑时重启)和扩展的页面数据(立即重新获取,不等下一次定时检查)。扩展本身由浏览器的
118
+ 扩展商店更新。
85
119
  - 全部命令见 `voyager --help`。状态保存在 `~/.voyager`(或 `$VOYAGER_HOME`),只有你的用户能读。
86
120
  - 已在 Chrome 中测试。Edge 和 Firefox 版的 Voyager 也带这个桥;Safari 版没有。
87
121
 
122
+ ## 须知与免责
123
+
124
+ - Voyager 和 Voyager CLI 是社区开源项目,与 OpenAI 无关,也没有得到 OpenAI 的认可。
125
+ - 本地桥会在你自己登录的浏览器里自动操作 ChatGPT 网页版。OpenAI 的[使用条款](https://openai.com/policies/terms-of-use/)限制以自动或程序化的方式提取输出,使用前请自行判断是否符合条款;账号因此受到的任何限制,由你自己承担。
126
+ - 同类工具也是这样处理的:例如 [oracle](https://github.com/steipete/oracle) 把浏览器模式作为需要主动开启的实验功能,并建议在意风险的人改用 API。需要有保障的用法,请使用 OpenAI API。
127
+ - 本地桥是给你在自己电脑上、为自己方便而用的:只连你自己的账号,不要拿它对外提供服务、共享账号或转卖额度,也只用于合法用途。
128
+
88
129
  ## 许可证
89
130
 
90
131
  MIT。开发说明见 [CONTRIBUTING.md](CONTRIBUTING.md)。