Use the Anectico 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:

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:

anectico login
anectico whoami

For CI or an AI agent, use a narrowly scoped API key:

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

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 <test-customer> --trace-id <actual-trace-id> --error-message '<exact-test-error>' to verify the stored customer, trace, and error in the active project. Mobile uses --story-kind mobile and --event-name <test-event> without a trace ID. See Instrumentation diagnostics.

Investigate a customer

anectico persons search buyer@acme.example
anectico persons timeline <person-id>
anectico issues list --status new
anectico issues affected <issue-id>
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 <incident-id> --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

anectico investigate start --anchor-kind issue --anchor-ref <group-id> "who does this hit"
anectico investigate continue <investigation-id> "was it the latest release"
anectico investigate get <investigation-id>
anectico investigate list --anchor-kind person --anchor-ref buyer@acme.example
anectico investigate watch <investigation-id> --state-file .anectico/watch.cursor --output json
anectico investigate cancel <investigation-id> --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 <investigation-id> 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

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:

anectico issues --help
anectico incidents create --help

The CLI command reference 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:

anectico traces delete <trace-id> --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
• Use permissions and actions safely
• CLI command reference

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.