octocode-cli 1.5.0 → 1.5.1

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.
Files changed (3) hide show
  1. package/README.md +149 -91
  2. package/package.json +1 -1
  3. package/assets/example.png +0 -0
package/README.md CHANGED
@@ -10,7 +10,8 @@
10
10
 
11
11
  [Website](https://octocode.ai) · [CLI Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/reference/CLI_REFERENCE.md) · [GitHub](https://github.com/bgauryy/octocode-mcp)
12
12
 
13
- <img src="https://raw.githubusercontent.com/bgauryy/octocode-mcp/main/packages/octocode-cli/assets/example.png" alt="Octocode CLI Demo" width="700" style="border-radius: 8px; margin: 20px 0;">
13
+ <img src="https://github.com/bgauryy/octocode-mcp/raw/main/packages/octocode-mcp/assets/logo_white.png" width="400px" alt="Octocode Logo">
14
+
14
15
 
15
16
  </div>
16
17
 
@@ -19,9 +20,12 @@
19
20
  ## Install
20
21
 
21
22
  ```bash
22
- # Homebrew (macOS / Linux) — installs the `octocode` command
23
+ # Homebrew (macOS / Linux): installs the `octocode` command globally
23
24
  brew install bgauryy/octocode/octocode
24
25
 
26
+ # equivalent short form
27
+ brew tap bgauryy/octocode && brew install octocode
28
+
25
29
  # or npm (global)
26
30
  npm install -g octocode-cli
27
31
 
@@ -29,113 +33,166 @@ npm install -g octocode-cli
29
33
  npx octocode-cli install
30
34
  ```
31
35
 
32
- The installed command is **`octocode`** (e.g. `octocode --help`).
36
+ Verify, then sign in:
37
+
38
+ ```bash
39
+ octocode --version # → octocode v1.5.0
40
+ octocode login # GitHub OAuth (device flow)
41
+ ```
42
+
43
+ The installed command is **`octocode`** (not `octocode-cli`). Homebrew pulls in Node automatically.
33
44
 
34
45
  ## Quick Start
35
46
 
36
47
  ```bash
37
- npx octocode-cli install # Interactive setup wizard
38
- octocode install --ide cursor # Install for a specific IDE
39
- octocode install --ide cursor --check # Pre-flight: check writability & current state
40
- octocode auth # GitHub authentication
48
+ octocode login # GitHub authentication
49
+ octocode install --ide cursor # wire MCP into an editor
50
+ octocode install --ide cursor --check # pre-flight: check writability & current state
51
+ octocode skills install --targets claude-code # add Agent Skills
52
+ octocode tools # list every tool
53
+ octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}'
41
54
  ```
42
55
 
43
56
  ---
44
57
 
58
+ ## The 14 Tools
59
+
60
+ Call any tool directly from the terminal. Great for scripts, pipelines, and one-off queries. No MCP server required.
61
+
62
+ | Group | Tool | What it does |
63
+ |-------|------|--------------|
64
+ | **GitHub** | `githubSearchCode` | Search code across GitHub `[EXTERNAL]` |
65
+ | | `githubSearchRepositories` | Search repositories by keywords/topics `[EXTERNAL]` |
66
+ | | `githubSearchPullRequests` | Search pull requests `[EXTERNAL]` |
67
+ | | `githubGetFileContent` | Read file content (matchString, line ranges) `[EXTERNAL]` |
68
+ | | `githubViewRepoStructure` | List a repo's directory tree `[EXTERNAL]` |
69
+ | | `githubCloneRepo` | Clone a repo/subtree to disk for local + LSP analysis |
70
+ | **Local** | `localSearchCode` | Search code patterns with ripgrep (PCRE2) |
71
+ | | `localFindFiles` | Find files by name/metadata |
72
+ | | `localGetFileContent` | Read local file content |
73
+ | | `localViewStructure` | View a local directory tree |
74
+ | **LSP** | `lspGotoDefinition` | Navigate to a symbol's definition |
75
+ | | `lspFindReferences` | Find all usages of a symbol |
76
+ | | `lspCallHierarchy` | Trace function call relationships |
77
+ | **Package** | `packageSearch` | Resolve npm / PyPI packages to their source repo |
78
+
79
+ ```bash
80
+ # Discover
81
+ octocode tools # list all tools
82
+ octocode tools localSearchCode # show one tool's schema
83
+ octocode tools localSearchCode githubSearchCode # batch schemas
84
+ octocode instructions # full MCP instructions + all schemas
85
+
86
+ # Run
87
+ octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}'
88
+ octocode tools githubSearchCode --queries '{"keywordsToSearch":["useReducer"],"owner":"facebook","repo":"react"}'
89
+ octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}' --json # machine-readable
90
+ ```
91
+
92
+ The shared metadata fields (`id`, `researchGoal`, `reasoning`, `mainResearchGoal`) are auto-filled. Provide only tool-specific fields.
93
+
94
+ ---
95
+
45
96
  ## GitHub Token
46
97
 
47
- Octocode resolves a GitHub token in this order: **environment variable → Octocode-managed token (`auth login`) → `gh` CLI**.
98
+ Octocode resolves a GitHub token in this order: **environment variable → Octocode-managed token (`octocode login`) → `gh` CLI**.
48
99
 
49
100
  For env-based setup, any of these are accepted (checked in this priority): `OCTOCODE_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`.
50
101
 
51
102
  ```bash
52
103
  export GITHUB_TOKEN=ghp_xxx # or OCTOCODE_TOKEN / GH_TOKEN
53
- octocode token --source # show which token & source is being used
54
- octocode token --validate # ping the GitHub API to verify it
104
+ octocode token --source # show which token & source is being used
105
+ octocode token --validate # ping the GitHub API to verify it
55
106
  ```
56
107
 
57
108
  ---
58
109
 
59
- ## Run Tools
110
+ ## Commands
111
+
112
+ | Command | Aliases | What it does |
113
+ |---------|---------|--------------|
114
+ | `install --ide <ide>` | `i`, `setup` | Configure octocode-mcp for an IDE |
115
+ | `install --ide <ide> --check` | | Pre-flight: verify config path is writable, show what would change |
116
+ | `install --ide <ide> -m <npx\|direct>` | | Choose install method (default `npx`; `direct` points at a local binary) |
117
+ | `install --ide <ide> --force` | | Overwrite an existing configuration |
118
+ | `install --ide <ide> --rollback` | | Restore the most recent backup configuration |
119
+ | `install --ide <ide> --rollback --backup-path <file>` | | Restore a specific backup file |
120
+ | `auth` / `login` / `logout` | `a`, `gh` / `l` / | GitHub authentication |
121
+ | `login --force` | | Log out the current session and re-authenticate in one step |
122
+ | `login --git-protocol <ssh\|https>` | | Set the git protocol used for clones |
123
+ | `login --hostname <host>` | | Target a GitHub Enterprise host |
124
+ | `logout --yes` | | Skip the confirmation prompt |
125
+ | `auth refresh` | | Refresh an Octocode-managed token (source-aware) |
126
+ | `token` | `t` | Print the resolved GitHub token |
127
+ | `token --type <auto\|octocode\|gh>` | | Force a specific token source instead of auto-resolution |
128
+ | `token --source` | | Show which source resolved the token |
129
+ | `token --validate` | | Ping the GitHub API to verify the token and show rate-limit |
130
+ | `status` | `s` | Full health check: auth + MCP clients + cache |
131
+ | `status --sync` | | Also include per-MCP sync analysis |
132
+ | `sync` | `sy` | Sync MCP configs across all IDEs |
133
+ | `sync --dry-run` | | Show what `sync` would do without writing anything |
134
+ | `sync --status` | | Show sync analysis without syncing |
135
+ | `sync --force` | | Auto-resolve conflicts (use first variant found) |
136
+ | `skills` | `sk` | Install / remove / list / search / read / sync skills |
137
+ | `skills search --direct` | | Search skills.sh directly (human-readable) |
138
+ | `skills search --direct --install` | | Fetch and install top result automatically |
139
+ | `skills read <path\|github:owner/repo/name>` | | Preview a SKILL.md from disk or GitHub (`--full` for untruncated) |
140
+ | `skills install --targets <t1,t2>` | | Install all bundled skills to targets |
141
+ | `skills install --skill <name> --targets <t>` | | Install one specific skill |
142
+ | `skills install --local <path> --targets <t>` | | Install a local skill folder |
143
+ | `skills install --dry-run` | | Preview installs without writing |
144
+ | `skills install --mode <copy\|symlink>` | | Symlink instead of copy (default `copy`) |
145
+ | `skills remove --skill <name> --targets <t>` | | Remove a skill |
146
+ | `skills list` / `skills list --target <t>` | | List installed skills (optionally filter to one target) |
147
+ | `skills sync <from> <to>` | | Copy skills between targets |
148
+ | `mcp list` | | Scan all OS MCP config files |
149
+ | `mcp list --client <id>` | | Search registry for a specific client |
150
+ | `mcp list --installed` | | List only installed MCPs with env-var status |
151
+ | `mcp list --search <text>` / `--category <name>` | | Filter the list |
152
+ | `mcp status --client <id>` | | Show servers in one config + env var status |
153
+ | `mcp install --id <id> --client <id>` | | Install one MCP server |
154
+ | `mcp install --id a,b,c` | | Batch-install MCPs (parallel preflight) |
155
+ | `mcp install --id <id> --config <path>` | | Install into a custom config file |
156
+ | `mcp install --id <id> --env K=V,K2=V2` | | Set env vars for the installed server |
157
+ | `mcp install --id <id> --force` | | Overwrite an existing entry |
158
+ | `mcp remove --id <id> --client <id>` | | Remove an MCP server |
159
+ | `cache status` | | Inspect cache sizes (repos, skills, logs) |
160
+ | `cache clean --all` | | Clean repos + skills + logs |
161
+ | `cache clean --repos` / `--skills` / `--logs` | | Clean specific targets |
162
+ | `cache clean --tools` | | Clean all tool caches (local + lsp + api) |
163
+ | `cache clean --local` / `--lsp` / `--api` | | Clean individual tool caches |
164
+ | `cache clean --all --dry-run` | | Show what would be freed without deleting |
165
+ | `cache clean --all --yes` | | Skip the confirmation prompt |
166
+ | `tools [name...]` | | List tools, show schema(s), or run with `--queries '<json>'` |
167
+ | `instructions` | | Print MCP instructions + every tool schema |
168
+
169
+ Most subcommands accept `--hostname <host>` for GitHub Enterprise.
60
170
 
61
- Call any of the 14 Octocode tools directly from the terminal — great for scripts, pipelines, and one-off queries.
62
-
63
- ```bash
64
- # Discover tools
65
- octocode tools # list all tools with descriptions
66
- octocode tools localSearchCode # show schema for a specific tool
67
- octocode tools localSearchCode githubSearchCode # batch schemas
171
+ ---
68
172
 
69
- # Run a tool
70
- octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}'
71
- octocode tools githubSearchCode --queries '{"keywordsToSearch":["useReducer"],"owner":"facebook","repo":"react"}'
173
+ ## Global Flags
72
174
 
73
- # Machine-readable output
74
- octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}' --json
175
+ | Flag | Description |
176
+ |------|-------------|
177
+ | `--json`, `-j` | Raw JSON output (machine-readable) |
178
+ | `--version`, `-v` | Print the CLI version |
179
+ | `--help`, `-h` | Show help for the CLI or a command |
75
180
 
76
- # Full MCP instructions + all schemas (for agents)
77
- octocode instructions
78
- ```
181
+ ## Environment
79
182
 
80
- Shared fields (`id`, `researchGoal`, `reasoning`, `mainResearchGoal`) are auto-filled — only provide tool-specific fields.
183
+ | Variable | Purpose |
184
+ |----------|---------|
185
+ | `OCTOCODE_TOKEN` | GitHub token (checked first) |
186
+ | `GH_TOKEN` | GitHub token (checked second) |
187
+ | `GITHUB_TOKEN` | GitHub token (checked third) |
188
+ | `OCTOCODE_HOME` | Override the data directory (default `~/.octocode`) |
81
189
 
82
- ---
190
+ ## Exit Codes
83
191
 
84
- ## Manage Octocode
85
-
86
- | Command | What it does |
87
- |---------|--------------|
88
- | `install --ide <ide>` | Configure octocode-mcp for an IDE |
89
- | `install --ide <ide> --check` | Pre-flight: verify config path is writable, show what would change |
90
- | `install --ide <ide> --rollback` | Restore the most recent backup configuration |
91
- | `install --ide <ide> --rollback --backup-path <file>` | Restore a specific backup file |
92
- | `auth` / `login` / `logout` | GitHub authentication |
93
- | `login --force` | Log out the current session and re-authenticate in one step |
94
- | `login --git-protocol <ssh\|https>` | Set the git protocol used for clones |
95
- | `logout --yes` | Skip the confirmation prompt |
96
- | `auth refresh` | Refresh an Octocode-managed token (source-aware) |
97
- | `token` | Print the resolved GitHub token |
98
- | `token --type <auto\|octocode\|gh>` | Force a specific token source instead of auto-resolution |
99
- | `token --source` | Show which source resolved the token |
100
- | `token --validate` | Ping the GitHub API to verify the token and show rate-limit |
101
- | `status` | Full health check: auth + MCP clients + cache |
102
- | `status --sync` | Also includes per-MCP sync analysis |
103
- | `sync` | Sync MCP configs across all IDEs |
104
- | `sync plan` / `sync --dry-run` | Show what `sync` would do without writing anything |
105
- | `sync --status` | Show sync analysis without syncing |
106
- | `sync --force` | Auto-resolve conflicts (use first variant found) |
107
- | `skills` | Install / remove / list / search / read bundled skills |
108
- | `skills search --direct` | Search skills.sh directly (human-readable) |
109
- | `skills search --direct --install` | Fetch and install top result automatically |
110
- | `skills read <path\|github:owner/repo/name>` | Preview a SKILL.md from disk or GitHub |
111
- | `skills install --targets <t1,t2>` | Install all bundled skills to targets |
112
- | `skills install --skill <name> --targets <t>` | Install one specific skill |
113
- | `skills install --local <path> --targets <t>` | Install a local skill folder |
114
- | `skills install --dry-run` | Preview installs without writing |
115
- | `skills install --mode symlink` | Symlink instead of copy |
116
- | `skills remove --skill <name> --targets <t>` | Remove a skill |
117
- | `skills list` | List all installed skills across all targets |
118
- | `skills list --target <t>` | Filter to one target |
119
- | `skills sync <from> <to>` | Copy skills between targets |
120
- | `mcp list` | Scan all OS MCP config files |
121
- | `mcp list --client <id>` | Search registry for a specific client |
122
- | `mcp list --installed` | List only installed MCPs with env-var status |
123
- | `mcp list --search <text>` | Filter by id / name / description / tags |
124
- | `mcp list --category <name>` | Filter by category |
125
- | `mcp status --client <id>` | Show servers in one config + env var status |
126
- | `mcp install --id <id> --client <id>` | Install one MCP server |
127
- | `mcp install --id a,b,c` | Batch-install MCPs (parallel preflight) |
128
- | `mcp install --id <id> --config <path>` | Install into a custom config file |
129
- | `mcp install --id <id> --env K=V,K2=V2` | Set env vars for the installed server |
130
- | `mcp install --id <id> --force` | Overwrite existing entry |
131
- | `mcp remove --id <id> --client <id>` | Remove an MCP server |
132
- | `cache status` | Inspect cache sizes (repos, skills, logs) |
133
- | `cache clean --all` | Clean repos + skills + logs |
134
- | `cache clean --repos` / `--skills` / `--logs` | Clean specific targets |
135
- | `cache clean --tools` | Clean all tool caches (local + lsp + api) |
136
- | `cache clean --local` / `--lsp` / `--api` | Clean individual tool caches |
137
- | `cache clean --all --dry-run` | Show what would be freed without deleting |
138
- | `cache clean --all --yes` | Skip confirmation prompt |
192
+ | Code | Meaning |
193
+ |------|---------|
194
+ | `0` | Success |
195
+ | `1` | Error |
139
196
 
140
197
  ---
141
198
 
@@ -148,22 +205,23 @@ Shared fields (`id`, `researchGoal`, `reasoning`, `mainResearchGoal`) are auto-f
148
205
  ## Troubleshooting
149
206
 
150
207
  ```bash
151
- octocode status --sync # Full health check including sync analysis
152
- octocode token --validate # Verify your GitHub token against the API
153
- octocode token --source # Debug token resolution chain
154
- octocode install --ide cursor --check # Pre-flight before installing
155
- octocode sync plan # Preview sync changes before applying
156
- octocode cache clean --all --dry-run # See what cache clean would free
208
+ octocode status --sync # Full health check including sync analysis
209
+ octocode token --validate # Verify your GitHub token against the API
210
+ octocode token --source # Debug token resolution chain
211
+ octocode install --ide cursor --check # Pre-flight before installing
212
+ octocode sync --dry-run # Preview sync changes before applying
213
+ octocode cache clean --all --dry-run # See what cache clean would free
157
214
  ```
158
215
 
159
216
  ---
160
217
 
161
218
  ## Docs
162
219
 
163
- - [CLI Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/reference/CLI_REFERENCE.md) — full command and flag reference
164
- - [Skills Guide](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/SKILLS_GUIDE.md) — bundled skills installation
220
+ - [CLI Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/reference/CLI_REFERENCE.md): full command and flag reference
221
+ - [Skills Guide](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/SKILLS_GUIDE.md): bundled skills installation
165
222
  - [Configuration Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/configuration/CONFIGURATION_REFERENCE.md)
166
223
  - [Troubleshooting](https://github.com/bgauryy/octocode-mcp/blob/main/docs/configuration/TROUBLESHOOTING.md)
224
+
167
225
  ---
168
226
 
169
227
  ## Privacy & Telemetry
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "octocode-cli",
3
- "version": "1.5.0",
3
+ "version": "1.5.1",
4
4
  "description": "Interactive CLI installer for octocode-mcp - Configure MCP servers for Cursor, Claude Desktop, and more",
5
5
  "keywords": [
6
6
  "ai-coding",
package/assets/example.png DELETED
Binary file