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

No CLI release is published yet. From an authorised repository checkout, with Go installed:

cd cli
go build -o ./bin/anectico ./cmd/anectico
export PATH="$PWD/bin:$PATH"
anectico version --output table

Use the checkout commit supplied during onboarding for repeatable 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 user_8842
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.

When a failed API response reflects the API key or bearer token attached to your request, the CLI replaces it with [redacted] in error codes, messages, recognized details, and terminal or JSON diagnostics. This also covers credentials represented with JSON escapes and failures received before a stream starts. Non-secret diagnostic text remains available.

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.

Connect an agent

One command mints a narrow key, merges the Anectico server into your agent's MCP configuration, installs the skill, and checks that the agent can use the connection, exiting 0 only if it can:

anectico agent bootstrap --project <project-id> --host claude
anectico agent doctor --host claude

--host is required and accepts claude, codex, cursor, gemini and muse. Muse Code is new: it was written from Meta's documentation and has not been tested on a real install, and the command says so. agent doctor re-runs the check on an existing setup and names exactly what is wrong. Bootstrap is a human-terminal onboarding exception: invoking it approves creation or reuse of the selected narrow key before an agent is connected. Connected agents must use the normal key preview and confirmation, and may never bootstrap to widen their own access. agent bootstrap --dry-run shows the change and makes none, and agent remove --host <host> --yes takes the entry out again. See Connect an AI agent with MCP for each host's configuration file, the secret handling, and the one step that is yours.

Give the CLI to an agent

anectico skill install claude
anectico skill install codex
anectico skill install cursor
anectico skill install gemini
anectico skill install muse
anectico docs

skill install writes the Anectico skills into the directory your agent reads skills from. The foundation skill, anectico-cli, teaches the CLI's conventions: JSON output, exit codes, --yes and project scoping. The skills are part of the CLI, so after you upgrade the CLI, bring them up to date:

anectico skill status claude
anectico skill upgrade claude

upgrade does not overwrite a skill you edited unless you pass --force. See Install the Anectico skills for the list of skills, where each agent keeps them, how to remove them, and the credential each one needs.

The generated command manifest lets an agent discover the installed CLI instead of relying on a copied command list.

Ask your agent

When an agent drives the CLI, each of these reads is a command it can run for you. The same reads are MCP tools. The last column shows the proof page that the MCP tool's link opens, when the result has one.

Job	MCP tool	CLI command	Proof page from the MCP result
Find a customer	search_persons	anectico persons search	Person
Read a customer's timeline	get_person_timeline	anectico persons timeline	Person
List error issues	list_issues	anectico issues list	Issue
Read the people an issue hit	get_affected_users	anectico issues affected	Issue
Search logs	search_logs	anectico logs query	none
Find traces	search_traces	anectico traces search	Trace

The CLI prints JSON when its output is piped. Its reads call the REST API and print no proof link. A command that runs an MCP tool, such as the saved-insight and audience writes, prints that tool's result, including its link. To get a proof link for a read, ask your agent to use the MCP tool. See Proof pages.

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

Commands with --confirm-token first print the server's preview. After approval, repeat the same arguments, retry key and version with that token. Commands declaring a local --yes confirmation require that flag. 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. 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.