# Tic CLI - Full Agent Operating Manual

Fast, native command-line tool and agent interface for the TIC (tic.io) business intelligence and datasets API (company, person, vehicle, and bankruptcy lookup). Built in Rust Edition 2024 for developers and autonomous AI agents.

## Architectural Guarantees

1. Sub-millisecond cold starts (1–3 ms), compiled with LTO and zero runtime dependencies.
2. Secure OS keystore credential management (macOS Keychain, Windows DPAPI, Linux Secret Service).
3. YAML by default on stdout for concise, readable inspection; `--json` outputs clean, structured JSON.
4. Error envelopes on stderr with deterministic machine-readable codes and remediation steps.
5. Fully offline mockable with `TIC_API_URL`.

## Exit Codes

| Code | Machine Name | Meaning | Remediation |
|:---|:---|:---|:---|
| 0 | `ok` | Command completed successfully | None |
| 1 | `error` | General or unclassified error | Report error and stop |
| 2 | `network` | Request timed out or network error | Retry once, then stop |
| 3 | `auth_required` | Missing or invalid API key | Set TIC_API_KEY, pass --api-key, or run tic login |
| 4 | `not_found` | Resource does not exist | Do not retry |
| 5 | `rate_limited` | Rate limit (429) reached | Exponential backoff before retrying |
| 6 | `invalid_input` | Parameter or validation error | Fix the CLI arguments |
| 7 | `no_account` | No account specified and none found | Run tic accounts list |

## Detailed Command Reference

### Global Flags
- `--json`: Force JSON output on stdout and stderr.
- `--format <format>`: Optional output format override (`yaml`, `json`).
- `-a, --account <name>`: Specify stored account name.
- `--api-key <key>`: Pass API key directly.
- `--verbose`: Print HTTP request and response information to stderr.

### Authentication & Accounts
- `tic login [<name>] [--api-key <key>] [--api-key-stdin] [--no-browser] [--force] [--no-verify]`
  Authenticate interactively or with provided key. Stores key in OS keystore.
- `tic accounts add <name> [--api-key <key>] [--api-key-stdin] [--force] [--no-verify]`
  Add or replace an account in the local configuration.
- `tic accounts list [--check]`
  List all configured accounts. With `--check`, verifies keys against live API.
- `tic accounts test <name>`
  Test connectivity for a specific account.
- `tic accounts remove <name> [--yes]`
  Remove an account and wipe its stored secret.

### Company Commands
- `tic company get <REG_NR>`
  Look up company by Swedish organization number (e.g. 556792-6687). Hyphens are automatically stripped.
- `tic company get-by-id <COMPANY_ID>`
  Look up company by internal TIC integer identifier.
- `tic company search <QUERY> [--query-by <fields>] [--filter-by <filter>] [--sort-by <sort>] [--per-page <n>]`
  Search company database. Default query-by: `names.nameOrIdentifier`.
- `tic company graph <COMPANY_ID> [--include-beneficial-owners <bool>] [--max-nodes <n>] [--max-roles <n>]`
  Fetch ownership network graph.
- `tic company tree <COMPANY_ID>`
  Fetch corporate group structure and ownership hierarchy tree.
- `tic company intelligence <COMPANY_ID>`
  Fetch intelligence anomalies, warnings, and fraud indicators.
- `tic company beneficial-owners <COMPANY_ID>`
  List ultimate beneficial owners (UBO) for the company.
- `tic company parties <COMPANY_ID>`
  List board members, executives, auditors, and signatories.
- `tic company debtor-summary <COMPANY_ID>`
  Retrieve debt enforcement summary (Kronofogden unpaid debts and balances).
- `tic company vehicles <COMPANY_ID> [--page <n>] [--page-size <n>]`
  List motor vehicles registered to the company.
- `tic company properties <COMPANY_ID> [--include-historical]`
  List real estate and properties owned by the company.

### Person Commands
- `tic person search <QUERY> [--page-size <n>]`
  Search individuals by personal identity number (personnummer). Supports `%` wildcards.
- `tic person get <PERSON_ID>`
  Retrieve detailed personal information.
- `tic person companies <PERSON_ID> [--page-size <n>]`
  List all companies where the person currently holds or previously held roles.

### Vehicle Commands
- `tic vehicle search <QUERY> [--query-by <field>] [--filter-by <filter>] [--sort-by <sort>] [--per-page <n>]`
  Search vehicle registry by licence plate (default), VIN, or make.

### Bankruptcy Commands
- `tic bankruptcy search <QUERY> [--query-by <field>] [--filter-by <filter>] [--sort-by <sort>] [--per-page <n>]`
  Search Swedish bankruptcy records by registration number or company name.

### Generic Search
- `tic search <COLLECTION> <QUERY> [--query-by <field>] [--filter-by <filter>] [--sort-by <sort>] [--per-page <n>]`
  Search any TIC collection directly.

### Agent Manual
- `tic agent-readme [--json]`
  Self-documenting manual embedded directly in binary.