Skip to content

Commit 0a8fb50

Browse files
authored
docs: update ccc skill install + init guidance (#134)
Follow-up to #132: the skill's management.md still said `pipx install cocoindex-code` and described `ccc init` as a purely non-interactive command. Update to reflect: - Two install styles — `[default]` (batteries included) vs bare (slim, LiteLLM-only). - First-run `ccc init` is interactive; prompts for provider/model and runs a test embed via the daemon. - `--litellm-model MODEL` flag for non-TTY / scripted use. - Pointer to `ccc doctor` if the init model test fails.
1 parent baa69ee commit 0a8fb50

1 file changed

Lines changed: 21 additions & 6 deletions

File tree

skills/ccc/references/management.md

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,15 @@
22

33
## Installation
44

5-
Install CocoIndex Code via pipx:
5+
Install CocoIndex Code via pipx. Two install styles:
66

77
```bash
8-
pipx install cocoindex-code
8+
pipx install 'cocoindex-code[default]' # batteries included (local embeddings via sentence-transformers)
9+
pipx install cocoindex-code # slim (LiteLLM-only; requires a cloud embedding provider + API key)
910
```
1011

12+
The `[default]` extra pulls in `sentence-transformers` so the first-run default (local embeddings, no API key) works out of the box. The slim install is for environments where you don't want the torch/transformers deps and plan to use a LiteLLM-supported cloud provider instead.
13+
1114
To upgrade to the latest version:
1215

1316
```bash
@@ -24,15 +27,27 @@ Run from the root directory of the project to index:
2427
ccc init
2528
```
2629

27-
This creates:
28-
- `~/.cocoindex_code/global_settings.yml` (user-level settings, e.g., model configuration) if it does not already exist.
29-
- `.cocoindex_code/settings.yml` (project-level settings, e.g., include/exclude file patterns).
30+
**First run (global settings don't exist yet)**`ccc init` prompts interactively for the embedding provider (sentence-transformers / litellm) and model, then runs a one-off test embed via the daemon to confirm the model works. Accept the defaults for the sentence-transformers path, or pick litellm and enter a model identifier.
31+
32+
**Subsequent runs** (global settings already exist) — prompts are skipped; only project settings and `.gitignore` are set up.
33+
34+
To skip the interactive prompts on the first run (e.g. in a script or container), pass `--litellm-model MODEL`:
35+
36+
```bash
37+
ccc init --litellm-model openai/text-embedding-3-small
38+
```
39+
40+
This is also the only way to pick a LiteLLM model when stdin isn't a TTY and you've done a slim install.
41+
42+
`ccc init` creates:
43+
- `~/.cocoindex_code/global_settings.yml` (user-level, embedding config + env vars).
44+
- `.cocoindex_code/settings.yml` (project-level, include/exclude patterns).
3045

3146
If `.git` exists in the directory, `.cocoindex_code/` is automatically added to `.gitignore`.
3247

3348
Use `-f` to skip the confirmation prompt if `ccc init` detects a potential parent project root.
3449

35-
After initialization, edit the settings files if needed (see [settings.md](settings.md) for format details), then run `ccc index` to build the initial index.
50+
After initialization, edit the settings files if needed (see [settings.md](settings.md) for format details), then run `ccc index` to build the initial index. If the model test printed `[FAIL]` during `init`, edit `global_settings.yml` (and optionally add API keys under the commented `envs:` block) and verify with `ccc doctor` before indexing.
3651

3752
## Troubleshooting
3853

0 commit comments

Comments
 (0)