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

# JSON Contract

> The stdout, stderr, error envelope, and exit-code contract for agentic CLI usage.

Pass `--json` whenever another process will consume the output.

```bash theme={null}
sf query "Fed rate cut" --json --limit 3
sf world --delta --json --since 1h
sf portfolio history --json --ticks 20 --trades 10
sf describe --all --json
```

## Stdout

In JSON mode, stdout is one valid JSON document.

```bash theme={null}
sf portfolio history --json --ticks 2 --trades 2
```

```json theme={null}
{
  "ok": true,
  "command": "portfolio.history",
  "data": {
    "ticks": [],
    "trades": []
  },
  "meta": {
    "ticks": 2,
    "trades": 2,
    "fetchedAt": "2026-04-30T00:00:00.000Z"
  }
}
```

Some public API passthrough commands return the documented API object directly when the server object is already stable.

```bash theme={null}
sf inspect KXRATECUT-26DEC31 --json
```

That response may be a market dossier object rather than a CLI envelope. Parse the response by shape: if `ok` is present, use the envelope; otherwise use the API page for that endpoint.

## Error envelope

Validation, auth, upstream, and runtime errors use a JSON envelope when JSON mode is active.

```json theme={null}
{
  "ok": false,
  "command": "query",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Query must be at least 2 characters.",
    "status": 400,
    "details": {
      "field": "query"
    }
  },
  "meta": {
    "fetchedAt": "2026-04-30T00:00:00.000Z"
  }
}
```

## Exit codes

| Code | Meaning                   |
| ---: | ------------------------- |
|  `0` | Success                   |
|  `1` | Runtime or internal error |
|  `2` | Usage or validation error |
|  `3` | Auth or config error      |
|  `4` | Upstream unavailable      |
|  `5` | Timeout or rate limit     |

## Payload controls

Use the command manifest or `--help` for the exact flags supported by each command.

| Flag                         | Use                                                             |
| ---------------------------- | --------------------------------------------------------------- |
| `--limit <n>`                | Bound result count.                                             |
| `--since <duration-or-date>` | Start from a time window or date.                               |
| `--until <date>`             | Stop at a date.                                                 |
| `--cursor <token>`           | Continue paginated history.                                     |
| `--include <list>`           | Request large optional fields, such as portfolio handoff notes. |
| `--compact`                  | Smaller response where supported.                               |
| `--raw`                      | Raw upstream/server object where supported.                     |

## Parsing rules

Agents should use this order:

1. Check the process exit code.
2. Parse stdout as JSON.
3. If the parsed object has `ok: false`, read `error`.
4. If the parsed object has `ok: true`, read `data`.
5. If `ok` is absent, treat it as a documented API passthrough object.

Do not scrape human terminal text. Use `--json`, `sf describe --all --json`, and the API reference pages.