> ## 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 `.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.

```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 `.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](/reference/local/index), [connect](/reference/local/connect), [call](/reference/local/call) and [receive](/reference/local/receive) for the applicable branch.

<Note>Reference follows the current development CLI and HTTP contracts. Hosted availability depends on the selected environment. See [capability status](/capability-status).</Note>