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
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/adopt-result writes. Ledger mutations also use a ledger lock. Receipt writes use a recoverable receipt-transaction.json journal. Preserve files and investigate an active writer before removing locks. Expired feed recovery can write snapshot-TIMESTAMP.json beside the ledger.

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; takes precedence over API_KEY and legacy saved cloud.token
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

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 stores non-secret metadata and removes the legacy saved token. Keep credentials in the process environment.

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

Arguments, output and status

​File ownership

​Environment and precedence

​Compatibility aliases until the cutover

​Arguments, output and status

File ownership

Environment and precedence

Compatibility aliases until the cutover

Arguments, output and status