CLI configuration and files

The CLI searches upward for a readable .linktrail/links.jsonl, then reads .linktrail/config.json at that root. 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 .linktrail/; 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
LINKTRAIL_TOKEN	Cloud API credential; takes precedence over API_KEY and legacy saved cloud.token
LINKTRAIL_API_KEY	Supported credential alias; if both credential variables differ, the command fails
LINKTRAIL_API_URL	Cloud origin; disagreement with saved cloud.origin fails
LINKTRAIL_WEBHOOK_SECRET	Full whsec_ signing secret used by receive
LINKTRAIL_GSC_TOKEN	Customer-supplied Google token for search context refresh
LINKTRAIL_GA4_TOKEN	Separate customer-supplied Google token for GA4 refresh

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.

Reference follows the current development CLI and HTTP contracts. Hosted availability depends on the selected environment. See capability status.

Overview

Cloud operations

Repository tools

HTTP and events

CLI configuration and files

File ownership

Environment and precedence

Arguments, output and status

​File ownership

​Environment and precedence

​Arguments, output and status

File ownership

Environment and precedence

Arguments, output and status