# Use the Anectico CLI > Investigate and operate Anectico from a terminal or coding agent. Canonical page: https://anectico.com/docs/agents/cli/ The Anectico CLI provides scriptable access to customer timelines, Issues, logs, traces, alerts, and the rest of the public platform surface. ## Install During early access, install the current source from the authorized repository: ```bash go install github.com/anectico/anectico/cli/cmd/anectico@main anectico version --output table ``` Pin the commit supplied during onboarding for repeatable automation. After tagged CLI releases begin, use `@latest` for interactive installation and pin a release version in automation. For automation, `anectico version --output json` returns the installed executable's name and injected release version without loading a profile or credentials. The conventional `anectico --version` flag remains available as plain text. ## Authenticate Humans can use the browser device flow: ```bash anectico login anectico whoami ``` For CI or an AI agent, use a narrowly scoped API key: ```bash export ANECTICO_API_KEY="an_..." anectico doctor ``` The CLI's built-in defaults are the managed service: `https://app.anectico.com` for REST commands and `https://api.anectico.com` for telemetry sent by `anectico send`. There is no localhost fallback — reaching a local stack needs `--api-url`/`ANECTICO_API_URL` (typically `http://localhost:8081`) and `--ingest-url`/`ANECTICO_INGEST_URL` (typically `http://localhost:4318`) set explicitly. `anectico doctor` checks both origins without writing telemetry. ## Select a project ```bash anectico projects use my-app ``` Commands use that project until you override it with a flag or profile. ## Verify application setup Your agent connection and your application's instrumentation are separate checks. Run `anectico doctor instrumentation --story-kind service --person --trace-id --error-message ''` to verify the stored customer, trace, and error in the active project. Mobile uses `--story-kind mobile` and `--event-name ` without a trace ID. See [Instrumentation diagnostics](/docs/instrument/diagnostics#verify-a-first-application). ## Investigate a customer ```bash anectico persons search buyer@acme.example anectico persons timeline anectico issues list --status new anectico issues affected anectico logs query --level error --since 1h anectico logs query --since 2026-08-02T21:58:18Z --until 2026-08-02T22:07:15Z anectico incidents watch --timeout 30m --output json ``` Commands whose help exposes the shared `--since` / `--until` window accept a positive duration such as `30m`, `6h`, or `7d`, or an exact RFC 3339 timestamp for either bound. Exact timestamps require `Z` or a numeric offset and are normalized to UTC before the request. Numeric offsets make repeated or skipped daylight-saving wall times unambiguous; named local time zones are not accepted. `--until` must resolve to an instant after `--since`. Pipe output to another process to receive JSON. Interactive terminals receive readable tables. Full-surface passthrough commands render a lossless `PATH / TYPE / VALUE` tree in table mode, including nested and empty containers; use `--output json` whenever another program consumes the result. Non-interactive failures are one JSON object on standard error with `error`, `message`, and `exit_code`. API failures also include the real HTTP `status`; local failures omit `status`. For `anectico send`, throttled responses also preserve the server's `Retry-After` value as `retry_after` so automation can back off without parsing message text. Unknown commands, bad flags, invalid local values, and missing or extra arguments exit with code 2. `anectico incidents watch` writes newline-delimited JSON: one current snapshot, then each newly appended timeline event with an opaque `cursor`. Restart it with the last successfully processed cursor to resume without replaying accepted events. The cursor is bound to the incident and project and is verified against the incident's own ordering of its timeline, so a resume point that no longer matches stops with an error rather than silently skipping or repeating events. Temporary transport, HTTP 408/429, and 5xx state is reported only on stderr as `reconnecting`/`connected` records. Use `--timeout`, `--max-polls`, `--max-events`, and `--max-transient-errors` to bound an automated observation window. Existing timeline history is skipped unless `--include-existing` is set. `--include-existing` starts a fresh replay and cannot be combined with `--cursor`. ## Ask the Customer Detective ```bash anectico investigate start --anchor-kind issue --anchor-ref "who does this hit" anectico investigate continue "was it the latest release" anectico investigate get anectico investigate list --anchor-kind person --anchor-ref buyer@acme.example anectico investigate watch --state-file .anectico/watch.cursor --output json anectico investigate cancel --yes ``` An investigation is anchored to exactly one subject. All seven anchor kinds use the same flag pair, `--anchor-kind` and `--anchor-ref`; `anectico investigate start --help` prints the reference grammar for each kind. The active project is applied to every anchor that accepts one. `start` and `continue` stream the turn as newline-delimited JSON: the persisted identifiers first, then progress updates, the answer in fragments, each validated citation, and a final answer or error. Because the identifiers arrive in the first record and the turn is stored from that moment, a stream that drops is recovered with `anectico investigate get ` rather than by asking the question again. Every citation is checked against the evidence the investigation was given before it is sent, so a citation always resolves to something real. `anectico investigate watch` follows an investigation's durable event journal. Each record carries an opaque `cursor`. Persist only the last record you finished processing and pass it back with `--cursor` to resume, or point `--state-file` at a file so an identical re-run continues where the previous one stopped; the cursor is written after every accepted event, so a run that is killed between two events still resumes from the second. Treat a cursor as opaque — never parse, compare, or construct one. A `caught_up` record proves delivery up to a point in the journal and deliberately does not move the resume position; only a `journal` record does. The stream ending without a terminal `caught_up` means the connection was interrupted, not that the investigation finished, so the command reconnects instead of reporting success. A resume cursor that is malformed, expired, ahead of the journal, or from another investigation is refused before any record is sent; the failure carries the code `cursor_refused`, and the recovery is `anectico investigate get`, then a resume from the `last_event_cursor` it returns. An unknown investigation is a separate failure with exit code 5 and is never presented as recoverable that way. `--timeout`, `--max-events`, `--max-reconnects`, and `--reconnect-delay` bound an automated observation window. `anectico investigate cancel` stops a running investigation and returns its settled state together with `last_event_cursor`. Cancelling one that is already cancelled succeeds; one whose answer already finished can no longer be stopped and the request is refused. ## Give the CLI to an agent ```bash anectico skill install claude anectico skill install codex anectico skill install cursor anectico docs ``` The generated command manifest lets an agent discover the installed CLI instead of relying on a copied command list. ## Look up commands and flags Every command supports `--help`. Use it at the group or leaf level: ```bash anectico issues --help anectico incidents create --help ``` The [CLI command reference](/docs/reference/cli) lists all current commands with their positional arguments, aliases, command-specific flags, defaults, and behavior. It is generated from the same command tree as `anectico docs`, so it is not a manually maintained shortlist. ## Writes and automation Destructive CLI commands require an explicit `--yes`. In CI, use a dedicated key, a fixed project, and JSON output. Never give an automation a human administrator key. Exact telemetry deletion uses the active project from `--project`, `ANECTICO_PROJECT`, or the selected profile: ```bash anectico traces delete --yes anectico logs delete <32-character-uppercase-log-id> --yes ``` The log command accepts only the canonical log ID; timestamp, trace, and span coordinates are not a deletion identity. Both commands preserve the server's idempotent, durable-suppression contract. - [Connect an AI agent with MCP](/docs/agents/connect-mcp) - [Use permissions and actions safely](/docs/agents/permissions-and-safety) - [CLI command reference](/docs/reference/cli) JSON request bodies that require an object reject `null`. Updating a saved search preserves large integers in existing JSON. Responses exceeding the CLI's read limits (64 MiB for JSON requests, 1 MiB for raw-upload acknowledgements) fail explicitly instead of returning truncated output.