# portfolio-intel CLI

> Parse CAS statements offline in your terminal — an interactive TUI and a headless command for scripts.

`portfolio-intel` is the parser as a command-line tool. It reads the PDF from
disk and parses it in-process: no account, no key, nothing uploaded.

> **Caution: Not on npm yet**
>
> The package is built and tested but has not been published. Until the first
> release the commands below will not install; the
> [browser terminal](https://docs.portfoliointel.co.in/local/overview#in-the-browser) runs the same parser today.

## Install

Requires Node.js 20 or later.

**npx**

```bash
npx @portfolio-intel/cli demo
```

**Global**

```bash
npm install -g @portfolio-intel/cli
portfolio-intel --version
```

## Interactive

```bash
portfolio-intel                  # open the terminal
portfolio-intel demo             # open it and run the bundled sample
portfolio-intel ~/Downloads/cas.pdf
```

```text
╭──────────────────────────────────────────────────────╮
│ ✻ Welcome to Portfolio Intel CAS parser v0.1.0       │
│                                                      │
│   /help for commands · /demo to try a sample         │
│   /parse <path>, or drop a PDF onto this window      │
╰──────────────────────────────────────────────────────╯

> /allocation

● Allocation by AMC · 7 fund houses
  SBI Mutual Fund        ████░░░░░░░░░░░░  27.7%  ₹8,33,149
  HDFC Mutual Fund       ███░░░░░░░░░░░░░  20.3%  ₹6,10,610
  PPFAS Mutual Fund      ███░░░░░░░░░░░░░  18.2%  ₹5,49,071
```

Drag a PDF onto the terminal window: the terminal types its path, and a bare
path to a `.pdf` is treated as `/parse <path>`. Password-protected statements
prompt for the password with masked input.

### Commands

| Command | What it does |
| --- | --- |
| `/demo` | Parse the bundled sample statement |
| `/parse [path]` | Parse a CAS PDF from disk |
| `/summary` | Value, invested amount and gain |
| `/holdings [filter]` | Holdings with units, NAV, value and weight |
| `/allocation` | Value by fund house, with a concentration warning above 40% |
| `/verify [fund]` | Recompute units × NAV and compare with the stated value |
| `/export` | Write the masked holdings as JSON to the current directory (never overwrites) |
| `/status`, `/privacy`, `/api`, `/clear`, `/help` | Session information and housekeeping |

Plain English works for the common ones: `show holdings`, `verify sbi small cap`.

### Keys

| Key | Action |
| --- | --- |
| `/` | Open the command menu; `↑` `↓` move, `tab` completes, `enter` runs |
| `↑` `↓` | Walk command history |
| `esc` | Interrupt a parse · close the menu · clear the line |
| `ctrl+c` | Interrupt a parse · clear the line · press twice to exit |
| `ctrl+l` | Clear the screen (the parsed statement stays loaded) |
| `ctrl+a` `ctrl+e` `ctrl+u` `ctrl+k` `ctrl+w` | Shell-style line editing |

## Headless, for scripts

`portfolio-intel parse` runs the same checks without the UI and exits.

```bash
portfolio-intel parse cas.pdf --json > holdings.json
```

1. **stdout is only the result** — the transcript as text, or with `--json` the
   masked snapshot. Diagnostics go to stderr; `--verbose` adds parser logs.

2. **Passwords never go on the command line.** Arguments are visible to every
   process on the machine and saved in shell history, so `--password` is
   refused. Use an environment variable or stdin:

   ```bash
   CAS_PASSWORD=ABCDE1234F portfolio-intel parse cas.pdf --password-env CAS_PASSWORD
   pass show cas | portfolio-intel parse cas.pdf --password-stdin --json
   ```

3. **The exit code says what happened.**

   | Code | Meaning |
   | --- | --- |
   | `0` | Parsed |
   | `1` | Not parsed — missing file, not a CAS, or no holdings found |
   | `2` | Usage error |
   | `3` | Password missing or wrong |

### JSON shape

```json
{
  "fileName": "cas.pdf",
  "source": "CAMS",
  "statementDate": "2025-12-31",
  "investor": "R**** S*****",
  "folioCount": 7,
  "holdings": [
    {
      "name": "SBI Small Cap Fund - Direct Growth",
      "amc": "SBI Mutual Fund",
      "folio": "••••4471",
      "isin": "INF200K01…",
      "units": 4521.84,
      "nav": 184.25,
      "value": 833148.97,
      "cost": 520000
    }
  ],
  "totalValue": 3013128.4,
  "totalCost": 2190000,
  "parseMs": 842,
  "sample": false
}
```

Names keep their shape but not their letters; folios keep only the last four
characters.

Source: https://docs.portfoliointel.co.in/local/cli/
