# CLI command reference

Every zfin subcommand, grouped the way [`zfin help`](version.md) groups
them. Each command has its own page with flags and sample output. For a
task-oriented path through these, see the
[user manual](../../README.md#the-user-manual-workflows).

```
zfin [global options] <command> [command options]
```

Get help at any time with `zfin help` or per command with
`zfin <command> --help`.

## Per-symbol lookups

| Command                   | Does                                               |
|---------------------------|----------------------------------------------------|
| [`perf`](perf.md)         | 1y/3y/5y/10y trailing returns (Morningstar-style)  |
| [`quote`](quote.md)       | Latest quote with a chart and 20-day history       |
| [`history`](history.md)   | Price history (symbol) or portfolio-value timeline |
| [`divs`](divs.md)         | Dividend history with TTM yield                    |
| [`splits`](splits.md)     | Split history                                      |
| [`options`](options.md)   | Options chain (all expirations)                    |
| [`earnings`](earnings.md) | Earnings history with EPS surprise, plus upcoming  |
| [`etf`](etf.md)           | ETF profile: holdings, sectors, AUM, inception     |

## Portfolio analysis

| Command                         | Does                                                      |
|---------------------------------|-----------------------------------------------------------|
| [`portfolio`](portfolio.md)     | Positions, valuations, and watchlist                      |
| [`analysis`](analysis.md)       | Breakdowns by asset class, sector, geo, account, tax type |
| [`exposure`](exposure.md)       | True exposure to a symbol (direct + look-through)         |
| [`review`](review.md)           | Per-holding performance and risk dashboard                |
| [`projections`](projections.md) | Retirement projections and percentile bands               |
| [`milestones`](milestones.md)   | Portfolio threshold crossings ($1M, doublings, ...)       |

## Time-series and journaling

| Command                             | Does                                            |
|-------------------------------------|-------------------------------------------------|
| [`snapshot`](snapshot.md)           | Write a portfolio snapshot to `history/`        |
| [`compare`](compare.md)             | Compare the portfolio at two points in time     |
| [`contributions`](contributions.md) | Money added/withdrawn between two git revisions |

## Data hygiene

| Command               | Does                                                |
|-----------------------|-----------------------------------------------------|
| [`audit`](audit.md)   | Reconcile against brokerage exports + hygiene check |
| [`enrich`](enrich.md) | Bootstrap `metadata.srf` from Wikidata + EDGAR      |
| [`import`](import.md) | Synthesize a portfolio file from a brokerage export |
| [`lookup`](lookup.md) | Resolve a CUSIP to a ticker via OpenFIGI            |

## Infrastructure

| Command                         | Does                                           |
|---------------------------------|------------------------------------------------|
| [`cache`](cache.md)             | Inspect or clear the local data cache          |
| [`doctor`](doctor.md)           | Health-check files and environment (read-only) |
| [`version`](version.md)         | Show version and build info                    |
| [`interactive`](interactive.md) | Launch the interactive TUI (alias `i`)         |

## Global options

These apply to every command and **must appear before** the
subcommand:

| Option                                | Effect                                                                                                                                                                    |
|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--no-color`                          | Disable colored output (also respects `NO_COLOR`).                                                                                                                        |
| `--refresh-data=<auto\|force\|never>` | Cache freshness policy. `auto` (default) respects TTLs; `force` re-fetches everything; `never` is offline. See [offline guide](../../guides/offline-and-refresh.md).      |
| `-p, --portfolio <PATTERN>`           | Portfolio file or glob (repeatable; default `portfolio*.srf`). Resolved against `ZFIN_HOME` when set, else the current directory. Quote globs to prevent shell expansion. |
| `-w, --watchlist <FILE>`              | Watchlist file (default `watchlist.srf`).                                                                                                                                 |

```bash
zfin --no-color --refresh-data=never -p 'portfolio_*.srf' analysis
```

`metadata.srf` and `accounts.srf` load from the same directory as the
first resolved portfolio file. See
[environment variables](../config/environment.md) for `ZFIN_HOME` and
related settings.

---

[Documentation home](../../README.md#reference)