> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentlinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI configuration and files

> Configure the ledger, environment credentials, output formats and local file ownership.

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](/reference/local/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.

```json theme={null}
{
  "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](/reference/local/migrate) instead.
* [receive](/reference/local/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](/reference/local/index), [connect](/reference/local/connect), [call](/reference/local/call) and [receive](/reference/local/receive) for the applicable branch.

<Note>Check the selected environment and workspace access before calling hosted operations. See [capability status](/capability-status).</Note>