@evident-ai/cli 3.1.1-dev.f24491c → 3.2.0

package/README.md

@@ -72,20 +72,21 @@ delivers any channel messages (e.g. Slack) to your local OpenCode.
 
 ```bash
 # Interactive: connect a specific runner
-evident run --agent <agent-id>
+evident run --runner <runner-id>
 
 # Drive a single conversation
-evident run --agent <agent-id> --conversation <conversation-id>
+evident run --runner <runner-id> --conversation <conversation-id>
 
 # CI: exit after 30s with no work
-evident run --agent <agent-id> --idle-timeout 30
+evident run --runner <runner-id> --idle-timeout 30
 ```
 
 Options:
 
-- `-a, --agent [id]` — Runner ID to connect to. Optional when `EVIDENT_AGENT_KEY`
+- `--runner [id]` — Runner ID to connect to. Optional when `EVIDENT_RUNNER_KEY`
   is set (the runner is then resolved automatically from the key).
-- `--runner [id]` — Alias for `--agent` (preferred name; wins if both are given).
+- `-a, --agent [id]` — Deprecated alias for `--runner`. Still supported, but it
+  prints a deprecation warning; `--runner` wins if both are given.
 - `-p, --port <port>` — OpenCode port (default: `4096`).
 - `--log-level <level>` — Log verbosity: `debug | info | warn | error` (default:
   `info`). Env: `EVIDENT_LOG_LEVEL`.
@@ -93,7 +94,53 @@ Options:
 - `-c, --conversation <id>` — Process only this specific conversation.
 - `--idle-timeout <seconds>` — Exit after N seconds with no pending work (useful
   in CI to avoid polling indefinitely).
+- `--opencode-start-timeout <seconds>` — How long to wait for OpenCode to become
+  healthy when the runner starts it itself (default: `180`). On expiry the runner
+  warns and comes online anyway rather than failing. Env:
+  `EVIDENT_OPENCODE_START_TIMEOUT` (seconds).
+- `--claude-usage-reporting <mode>` — Whether to report the local Claude Code
+  subscription's rate-limit usage to Evident, so it shows on the runner page:
+  `auto` (default) reports it when a usable Claude Code login is found on this
+  machine and stays silent otherwise; `on` forces reporting and warns loudly (and
+  keeps retrying) if no usable login is found; `off` disables it entirely — no
+  Claude credential is ever read. An unrecognized value falls back to `auto` with
+  a warning. Env: `EVIDENT_CLAUDE_USAGE_REPORTING`.
 - `--json` — Output in JSON format (forces non-interactive mode).
+- `--session-cleanup-max-age <duration>` — Delete OpenCode sessions idle longer
+  than this window (format `<number><unit>`, unit one of `s, m, h, d` — e.g.
+  `7d`, `24h`). Setting this (or `--session-cleanup-max-count`) is what enables
+  cleanup — there is no separate on/off flag. An invalid value is warned about
+  and ignored, which can leave cleanup off if it was the only rule set. Env:
+  `EVIDENT_SESSION_CLEANUP_MAX_AGE`.
+- `--session-cleanup-max-count <n>` — Keep only the newest N OpenCode sessions
+  by last activity, deleting the rest. Also enables cleanup; combines with
+  `--session-cleanup-max-age` as OR. A session with a turn actively in progress
+  is never deleted, regardless of either rule. Env:
+  `EVIDENT_SESSION_CLEANUP_MAX_COUNT`.
+- `--max-active-sessions <n>` — Cap how many sessions the runner will have
+  actively working at once (default: unlimited). Counts sessions with work in
+  flight and is per runner process, not global across runners. Once the cap is
+  reached, new work simply stays pending and is picked up on a later poll tick
+  — nothing is dropped or errored — but a follow-up into a conversation whose
+  session is already active is never blocked, since it costs no extra slot. A
+  legitimately long-running turn holds its slot for as long as it runs
+  (bounded only by the 6h absolute processing ceiling), so pick N with that in
+  mind. After a restart the runner re-adopts work it had already claimed,
+  which can briefly push the active count above the cap — that's deliberate;
+  the cap bounds new dispatch, not re-adoption. An invalid value (`0`,
+  negative, non-numeric) is warned about and falls back to unlimited. Env:
+  `EVIDENT_MAX_ACTIVE_SESSIONS`.
+- `--session-cleanup-interval <duration>` — How often the cleanup sweep runs
+  (default: `1h`). An invalid value falls back to the default rather than
+  disabling cleanup. Env: `EVIDENT_SESSION_CLEANUP_INTERVAL`.
+- `--enable-file-sync-to <dir>` — Let the runner write files Evident has queued
+  for it into this directory — it collects them as part of the polling it
+  already does, so they land a couple of seconds after you hand them over.
+  Repeatable (up to 16); each value must be absolute once a leading `~` is
+  expanded, and the filesystem root is rejected. Omit it entirely and the
+  runner collects nothing and refuses any queued file, telling you why. Use
+  `--enable-file-sync-to ~/.claude` to connect a Claude subscription from the
+  web — see the website's Model providers doc.
 
 ## Global flags
 
@@ -110,11 +157,27 @@ targets the **production** Evident platform by default.
   that runner and resolves the runner ID automatically, so `--runner`/`--agent`
   is not required. Ideal for CI/CD. Preferred name; wins over `EVIDENT_AGENT_KEY`
   if both are set.
-- `EVIDENT_AGENT_KEY` — Alias for `EVIDENT_RUNNER_KEY` (still fully supported).
+- `EVIDENT_AGENT_KEY` — Deprecated alias for `EVIDENT_RUNNER_KEY`. Still fully
+  supported, but `evident run` prints a deprecation warning when it is used
+  without `EVIDENT_RUNNER_KEY`.
 - `EVIDENT_TOKEN` — A user token used for authentication (alternative to a
   keychain login from `evident login`).
 - `EVIDENT_API_URL` — Override the API base URL (equivalent to `--endpoint`).
 - `EVIDENT_TUNNEL_URL` — Override the tunnel relay URL (equivalent to `--tunnel`).
+- `EVIDENT_CLAUDE_USAGE_REPORTING` — Equivalent to `--claude-usage-reporting`; the
+  flag wins if both are set.
+- `EVIDENT_LOG_LEVEL` — Equivalent to `--log-level`; the flag wins if both are
+  set, and `-v`/`--verbose` also outranks this env var.
+- `EVIDENT_OPENCODE_START_TIMEOUT` — Equivalent to `--opencode-start-timeout`
+  (seconds); the flag wins if both are set.
+- `EVIDENT_SESSION_CLEANUP_MAX_AGE` — Equivalent to `--session-cleanup-max-age`;
+  the flag wins if both are set.
+- `EVIDENT_SESSION_CLEANUP_MAX_COUNT` — Equivalent to
+  `--session-cleanup-max-count`; the flag wins if both are set.
+- `EVIDENT_MAX_ACTIVE_SESSIONS` — Equivalent to `--max-active-sessions`; the
+  flag wins if both are set.
+- `EVIDENT_SESSION_CLEANUP_INTERVAL` — Equivalent to
+  `--session-cleanup-interval`; the flag wins if both are set.
 
 Authentication precedence for `run`: `EVIDENT_RUNNER_KEY`/`EVIDENT_AGENT_KEY`
 (tied; `EVIDENT_RUNNER_KEY` wins if both are set) → `EVIDENT_TOKEN` →
@@ -141,20 +204,21 @@ ID.
 From your project directory, start the runner:
 
 ```bash
-evident run --agent <agent-id>
+evident run --runner <runner-id>
 ```
 
 `evident run` ensures `opencode serve` is running on `127.0.0.1:4096` (starting
 it if needed) and connects the tunnel. Once connected, the web shows the runner as
 online and you can open its chat.
 
-For CI or unattended use, set `EVIDENT_AGENT_KEY` and omit `--agent`:
+For CI or unattended use, set `EVIDENT_RUNNER_KEY` and omit `--runner`:
 
 ```bash
-EVIDENT_AGENT_KEY=<agent-key> evident run --idle-timeout 30
+EVIDENT_RUNNER_KEY=<runner-key> evident run --idle-timeout 30
 ```
 
-(`EVIDENT_RUNNER_KEY` is equivalent and the preferred name — use whichever you like.)
+(`EVIDENT_AGENT_KEY` is a still-supported deprecated alias for
+`EVIDENT_RUNNER_KEY`.)
 
 ## How it works
 
@@ -191,7 +255,7 @@ evident logout
 evident login
 ```
 
-In CI, make sure `EVIDENT_AGENT_KEY` (or `EVIDENT_TOKEN`) is set.
+In CI, make sure `EVIDENT_RUNNER_KEY` (or `EVIDENT_TOKEN`) is set.
 
 ### OpenCode isn't reachable