@codevector/cli 0.6.0 → 0.8.0

package/README.md

@@ -4,11 +4,13 @@ Wire your AI coding tools through a corporate gateway in one command. One API ke
 
 ```bash
 npm i -g @codevector/cli   # or: pnpm add -g @codevector/cli
-codevector auth login
-codevector configure
+codevector auth login      # once, to store your gateway + API key
+codevector init            # per repo: pin the gateway, name the project, wire your tools
 ```
 
-That's the whole onboarding. Pick a tool, pick a scope, done.
+That's the whole onboarding. `init` is the per-repo entry point - it pins a gateway,
+writes a `.codevector.json`, and offers to run `configure` for you. Add the shell hook
+(below) and your credentials auto-activate as you `cd` between repos.
 
 ---
 
@@ -21,22 +23,22 @@ That's the whole onboarding. Pick a tool, pick a scope, done.
 ## What it does
 
 - **Signs you in** with a per-seat API key issued by your gateway admin.
+- **Initializes a repo** with `codevector init`: pins a gateway, names the project for attribution, and offers to wire your tools in one pass.
 - **Writes the right config file** for each supported coding tool so its model traffic routes through the gateway instead of calling upstream providers directly.
 - **Picks the right scope** (global, project-wide, or per-machine) based on what you want and what the tool supports.
-- **Installs an acceptance-tracking hook** that fires at session end for tools that expose lifecycle events. Feeds the gateway's usage reporting.
+- **Auto-activates credentials on cd** via an optional shell hook, so each repo gets the gateway env vars for its pinned gateway without a per-tool config file.
 - **Stays out of your way.** Idempotent writes. Deep-merges into existing settings files — won't clobber your theme, your other hooks, your existing env vars.
 
 ---
 
 ## Supported tools
 
-| Tool                             | Config path (user scope)                 | Scopes (`configure` writes project/local; `system configure` writes user) | Key storage                                                | Hooks wired           |
-| -------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------- |
-| **Claude Code**                  | `~/.claude/settings.json`                | user / project / local                                                    | literal in JSON (`ANTHROPIC_AUTH_TOKEN`)                   | `Stop` + `SessionEnd` |
-| **opencode** (sst/opencode)      | `~/.config/opencode/opencode.json`       | user / project / local                                                    | literal (user + local); env-var reference in project scope | —                     |
-| **codex** (OpenAI codex CLI)     | `~/.codex/config.toml`                   | user / project / local                                                    | shell env var (codex does not auto-load `.env`)            | not wired             |
+| Tool                             | Config path (user scope)                 | Scopes (`configure` writes project/local; `system configure` writes user) | Key storage                                                |
+| -------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| **Claude Code**                  | `~/.claude/settings.json`                | user / project / local                                                    | literal in JSON (`ANTHROPIC_AUTH_TOKEN`)                   |
+| **opencode** (sst/opencode)      | `~/.config/opencode/opencode.json`       | user / project / local                                                    | literal (user + local); env-var reference in project scope |
 
-Each writer emits both Anthropic and OpenAI-compatible provider entries where the tool supports both wire formats. codex is OpenAI-only.
+Each writer emits both Anthropic and OpenAI-compatible provider entries where the tool supports both wire formats.
 
 ---
 
@@ -49,11 +51,11 @@ Scopes are split across two commands so global state can't get clobbered by acci
 
 | Scope     | Where the file lives                                                                             | Committed to git?               | Written by                  | Recommended for                                           |
 | --------- | ------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------- | --------------------------------------------------------- |
-| `user`    | your home directory (`~/.claude/…`, `~/.codex/…`, etc.)                                          | no (outside the repo)           | `codevector system configure` | your personal default across every project                |
-| `project` | this repo's config dir (`./.claude/settings.json`, `./.codex/config.toml`, etc.)                 | **yes** — shared with teammates | `codevector configure`      | base URL only; we never embed the API key here            |
-| `local`   | this repo's local-override file (`./.claude/settings.local.json`, `./opencode.json`, `./.codex/config.toml` + .gitignore) | no — auto-gitignored | `codevector configure`      | the usual default: per-seat API key stays on your machine |
+| `user`    | your home directory (`~/.claude/…`, `~/.config/opencode/…`, etc.)                               | no (outside the repo)           | `codevector system configure` | your personal default across every project                |
+| `project` | this repo's config dir (`./.claude/settings.json`, `./opencode.json`, etc.)                      | **yes** — shared with teammates | `codevector configure`      | base URL only; we never embed the API key here            |
+| `local`   | this repo's local-override file (`./.claude/settings.local.json`, `./opencode.json` + .gitignore) | no — auto-gitignored | `codevector configure`      | the usual default: per-seat API key stays on your machine |
 
-`local` is the default when you don't pass `--scope` to `configure`. The CLI adds gitignore entries automatically for tools that don't natively ignore their local file (opencode, codex).
+`local` is the default when you don't pass `--scope` to `configure`. The CLI adds gitignore entries automatically for tools that don't natively ignore their local file (opencode).
 
 **Secret hygiene:** `project` scope will never write your API key to disk. It writes an env-var reference (`{env:CODEVECTOR_GATEWAY_KEY}` or an `envKey` field) and prints a note telling you to export the variable yourself. This is the only safe way to commit a config file.
 
@@ -86,9 +88,14 @@ codevector status                             # who am I, where am I pointed, wh
 codevector doctor                             # health checks: creds, network, hook install, settings
 codevector version                            # print CLI version
 codevector update                             # update @codevector/cli from npm (use --with pnpm|yarn if needed)
-codevector init                               # writes .codevector.json (projectName + ticket pattern)
-codevector init --project my-app              # with explicit project name
-codevector init --ticket-pattern "JIRA-\d+"   # with custom ticket extraction regex
+codevector init                               # per-repo: pin gateway, name project, offer to wire tools
+codevector init --project my-app              # explicit project name
+codevector init --gateway https://gw.corp.com # pin a gateway non-interactively
+codevector init --ticket-pattern "JIRA-\d+"   # custom ticket extraction regex
+codevector init --skip-configure              # write .codevector.json, don't wire tools
+codevector init --force                       # overwrite an existing .codevector.json
+codevector hook bash                          # print the shell-hook snippet (bash|zsh|fish)
+codevector env --shell bash                   # print env exports for the current repo (used by the hook)
 ```
 
 Every command supports `--help`. Commands that need input will prompt interactively when flags are missing, but every flag still works for scripting.
@@ -110,10 +117,18 @@ codevector auth login --gateway-url https://gateway.corp.com --api-key "$KEY"  #
 
 ```bash
 codevector auth login              # paste the gateway URL + API key your admin emailed you
-codevector configure claude-code   # default scope is local — safe per-seat, gitignored
+codevector init                    # in the repo: pins the gateway, names the project, wires your tools
 codevector doctor                  # confirm everything's wired
 ```
 
+**Auto-activate credentials as you move between repos:**
+
+```bash
+# add to ~/.zshrc (or ~/.bashrc; fish: codevector hook fish | source)
+eval "$(codevector hook zsh)"
+# then: cd into any repo with a .codevector.json and its gateway env vars load automatically
+```
+
 **Configuring multiple tools in one go:**
 
 ```bash
@@ -130,7 +145,7 @@ codevector configure claude-code --scope local
 **Set global defaults across every editor for this machine:**
 
 ```bash
-codevector system configure          # writes user-scope config for Claude Code, opencode, and codex
+codevector system configure          # writes user-scope config for Claude Code and opencode
 codevector system restore --latest   # roll back the most recent run if needed
 ```
 
@@ -156,6 +171,32 @@ codevector models sync --scope local   # refresh model list after admin adds mod
 
 ---
 
+## Shell hook
+
+`codevector init` pins a gateway to a repo in `.codevector.json`. The shell hook reads
+that pin and exports the matching profile's gateway env vars whenever you `cd` into the
+repo, then clears them when you leave. Install it once:
+
+| Shell | rc file                      | Line to add                      |
+| ----- | ---------------------------- | -------------------------------- |
+| bash  | `~/.bashrc`                  | `eval "$(codevector hook bash)"` |
+| zsh   | `~/.zshrc`                   | `eval "$(codevector hook zsh)"`  |
+| fish  | `~/.config/fish/config.fish` | `codevector hook fish \| source` |
+
+On macOS, login shells read `~/.bash_profile` instead of `~/.bashrc`.
+
+After restarting your shell, entering a repo with a pinned gateway exports
+`ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_API_KEY`, and
+`ANTHROPIC_CUSTOM_HEADERS` (the `x-project` attribution header). The CLI walks up the
+directory tree, so a subdirectory of the repo resolves the same pin. If no saved profile
+matches the pinned gateway, the hook prints a hint to run `codevector auth login`.
+`codevector doctor` reports whether the hook is installed.
+
+`codevector env --shell <shell>` is the command the hook evaluates on each `cd` — you
+don't run it directly.
+
+---
+
 ## Safe config merging
 
 `codevector configure` adds the gateway settings to your existing config files without overwriting what's already there:
@@ -179,7 +220,6 @@ Override the config root with `CODEVECTOR_CONFIG_DIR`.
 ## Limitations
 
 - **Cursor requires manual setup.** Cursor stores its settings in an internal database, so the CLI can't configure it automatically. Find step-by-step instructions on your gateway dashboard.
-- **codex doesn't auto-load `.env`.** After configuring codex at any scope, export `CODEVECTOR_GATEWAY_KEY` in your shell rc yourself. The CLI prints the line to paste.
 - **`configure --scope user` is no longer accepted.** Use `codevector system configure` for machine-wide setup; it writes every editor in one pass and backs up existing files for rollback via `system restore`.
 
 ---
@@ -190,6 +230,5 @@ Override the config root with `CODEVECTOR_CONFIG_DIR`.
 | ---------------------- | --------------------------------------------------------- | ---------------------- |
 | Claude Code            | `~/.claude/settings.json` / `.claude/settings.local.json` | JSON                   |
 | opencode               | `~/.config/opencode/opencode.json` / `./opencode.json`    | JSON (JSONC tolerated) |
-| codex                  | `~/.codex/config.toml`                                    | TOML                   |
 | codevector credentials | `~/.config/codevector/credentials.json`                   | JSON (chmod 0600)      |
-| codevector hook script | `~/.config/codevector/hooks/acceptance.sh`                | shell                  |
+| codevector project pin | `<repo>/.codevector.json`                                 | JSON (no secrets)      |