CLI configuration and files

The CLI searches upward for a readable .agentlinkops/links.jsonl, then reads .agentlinkops/config.json at that root. An existing .linktrail/ directory is still read when no .agentlinkops/ exists beside it, with one hint per process; run migrate to rename it. If it finds no default ledger, it uses the current directory. Run init and mix from the intended repository root; they pin that directory explicitly. A custom ledger filename alone does not change upward root discovery.

{
  "project": {"id": "prj_example", "site": ["example.com"]},
  "cloud": {"origin": "https://app.agentlinkops.com", "workspaceId": "ws_example"},
  "paths": {},
  "defaults": {"concurrency": 6, "timeoutMs": 20000, "hostDelayMs": 2000}
}

File ownership

Paths in paths resolve relative to .agentlinkops/ (or the legacy directory in use); absolute paths remain absolute. Omitted paths use these defaults.

Config field	Default path	Contents and writer
ledger	links.jsonl	Human/agent intentions; add, adopt, receipt and formatting commands
receipts	receipts.jsonl	Local claims; receipt add
observations	observations.jsonl	Local checks and cloud observation projections
indexObservations	index-observations.jsonl	Imported and pulled index observation receipts
indexSubmissions	index-submissions.jsonl	Customer-declared indexing submission receipts
events	events.jsonl	Authenticated pulled event history
candidates	candidates.jsonl	Candidate mirror path; import previews do not write it
state	state.json	Check activity, cloud mappings, independent feed cursors and diagnostics
gsc	context/gsc.jsonl	Tool-owned search context rows
ga4	context/ga4.jsonl	Tool-owned business context rows
contextState	context/context-state.json	Provider context/cache state
siteFacts	context/site-facts.jsonl	Tool-owned public site facts
manual	context/manual.md	Authored site context
siteProfile	context/site-profile.md	Authored judgments with fact/manual citations

sync.lock protects check/sync/receive/compact writes and diagnostic state saves by doctor. Ledger mutations and adopt-result use a lock named for the ledger file. Receipt writes use a recoverable receipt-transaction.json journal. Preserve files and investigate an active writer before removing locks. Feed recovery saves snapshot-FEED-TIMESTAMP-UUID.json beside the ledger. See sync recovery for the explicit invalid-cursor recovery flags and doctor for diagnostic writer behavior.

Environment and precedence

Variable	Purpose and precedence
AGENTLINKOPS_PROXY_URL	Required for browser measurement starting with CLI 0.6.5; missing admission never falls back to direct traffic
AGENTLINKOPS_BROWSER_AUTH	Starting with CLI 0.6.7, defaults to accountless; saved browser sessions are never loaded in that mode. Optional legacy saved-session mode requires an explicit value of saved-session
AGENTLINKOPS_BROWSER_EGRESS	Defaults to proxy-required; explicitly authorized direct-diagnostic mode requires the proxy to be unset
AGENTLINKOPS_TOKEN	Cloud API credential; overrides legacy saved cloud.token. TOKEN and API_KEY must match when both are set
AGENTLINKOPS_API_KEY	Supported credential alias; if both credential variables differ, the command fails
AGENTLINKOPS_API_URL	Cloud origin; disagreement with saved cloud.origin fails
AGENTLINKOPS_WEBHOOK_SECRET	Full whsec_ signing secret used by receive
AGENTLINKOPS_GSC_TOKEN	Customer-supplied Google token for search context refresh
AGENTLINKOPS_GA4_TOKEN	Separate customer-supplied Google token for GA4 refresh
DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD	Credentials for explicitly selected DataForSEO citation measurement; explicit engine selection and budget checks still apply
PERPLEXITY_API_KEY	Credential for the explicitly selected Perplexity API citation engine
DUCK2API_URL	API base URL for the explicitly selected Duck2API citation engine; default http://127.0.0.1:8090/v1

Compatibility aliases until the cutover

The product is AgentLinkOps; Linktrail was its working name. During the private pilot compatibility window each old identifier keeps working with a notice, and none is removed until the dated cutover release recorded under DP-0029-T05, after pilot customers are notified.

linktrail runs the same CLI as agentlinkops after one line on stderr; stdout is unchanged, so --json readers are unaffected.
LINKTRAIL_TOKEN, LINKTRAIL_API_KEY, LINKTRAIL_API_URL, LINKTRAIL_WEBHOOK_SECRET, LINKTRAIL_GSC_TOKEN and LINKTRAIL_GA4_TOKEN are still read. When only the old name is set, the CLI uses it and warns once per process. When both names carry the same value, nothing is printed. When they differ, the command fails with exit 2 and names both variables; no value is ever printed.
An existing .linktrail/ directory is read when no .agentlinkops/ exists beside it, with one hint per process. init refuses to create .agentlinkops/ next to it; run migrate instead.
receive verifies AgentLinkOps-Signature and AgentLinkOps-Timestamp first and still accepts the Linktrail-* headers.

Saved identity aliases are accepted: cloud.workspaceId or cloud.workspace_id, and project.id, cloud.projectId or cloud.project_id. Conflicting identities fail. connect keeps ledger identity metadata separate from credentials and removes the legacy saved ledger token. Current source also supports a verified API key stored outside the repository; the connect reference records its release boundary. Environment keys remain supported. Follow the CLI setup guide for the published package.

OAuth credential custody

The optional Linux connect —oauth flow uses an existing public OAuth client, discovered issuer metadata and browser consent through a loopback callback. It stores tokens in the private user-owned ~/.agentlinkops/oauth/ directory. Ledger configuration retains the non-secret cloud.auth.credentialRef and an exact issuer/client/resource/workspace/project binding. It never copies tokens into the repository. OAuth-backed CLI calls use MCP, while API-key calls use HTTP. Remove conflicting API-key environment variables before selecting OAuth. Reconnecting to another project or issuer requires a matching binding; do not edit a reference to widen access. macOS and Windows credential custody are refused. A connected read does not verify a write grant. Follow CLI connection recovery for missing app approval, refresh and revocation.

Local writer coordination

Commands that acquire ledger or sync writer locks use the native advisory-lock dependency on macOS and Linux and fail closed when it is unavailable or the platform is unsupported. Follow the command’s documented recovery option after inspecting the recorded owner; file age alone does not establish stale ownership. Do not remove an active writer’s lock or restart its work merely because a marker exists. Reinstall missing platform dependencies before retrying a refused writer.

Arguments, output and status

The main argument parser accepts --name value and --name=value. Repeated flags work only where documented. A bare flag becomes true. There is no general promise that every command rejects every unknown flag; use the listed options. There is no global --json switch: each command owns its output shape. Most commands return 0 on success and 2 on errors. Ledger check, doctor, mix and profile citation checks also use 1 for their documented result conditions. A single-page check returns 0 even when its result is absent or unknown. Read that result’s state. Use local command reference, connect, call and receive for the applicable branch.

Check the selected environment and workspace access before calling hosted operations. See capability status.

Overview

MCP, CLI and API commands

CLI client

HTTP and events

Optional local workflows

CLI configuration and files

File ownership

Environment and precedence

Compatibility aliases until the cutover

OAuth credential custody

Local writer coordination

Arguments, output and status

​File ownership

​Environment and precedence

​Compatibility aliases until the cutover

​OAuth credential custody

​Local writer coordination

​Arguments, output and status

File ownership

Environment and precedence

Compatibility aliases until the cutover

OAuth credential custody

Local writer coordination

Arguments, output and status