# Everything Vitals sees, in your terminal.

Canonical page: https://vitalsmac.com/features/cli

Type `vitals` and get the apps using your Mac, the ports and dev servers each project holds, your coding agents and what is left of your AI plans. A table you can read, JSON your scripts can parse, and nothing stopped without your yes.

## Install: It comes with the app, or with Homebrew.

The command is inside Vitals. Turn on Let AI Assistants Ask Vitals in Settings → Integrations and Vitals puts `vitals` on your PATH, with its manual page and tab completion. Or install the app and the command together with one Homebrew line.

- Linked into `/opt/homebrew/bin` or `/usr/local/bin`
- A manual page: `man vitals`
- Tab completion for zsh, bash and fish
- One Homebrew line installs the app and the command

## Reading: What the window shows, as a table.

`vitals status` gives a line per reading with a bar. `vitals top` lists the apps using the most memory, CPU, power, disk or network, right now or over a year. Ports, projects, containers, agents and AI limits each have a command, and every answer says when it was measured.

- Apps with their helpers counted in, as in the window
- Each reading in the app’s own color
- Which ports are open to the network, and which to this Mac only
- `--watch` refreshes the answer every two seconds

## Scripts: JSON for scripts, CSV for spreadsheets.

Add `--json` and any answer is JSON a script can read, the same answer the MCP server gives. `--csv` gives the main list for a spreadsheet. In a pipe nothing is clipped, so a script or an agent reads every word.

- `--json` on every command
- `--csv` for the main list
- Plain text in a pipe, nothing clipped
- Exit code 1 when Vitals didn’t answer

## Stopping: It asks before it stops anything.

`vitals can-quit` says whether something is safe to quit, why, and what would stop with it. `vitals quit` and `vitals stop` show that verdict first and wait for your yes. What needs a person is refused without a terminal, even with `--yes`, so a script or an agent can't wave it through.

- Safe, ask first or don’t, with the reason
- `stop --idle` stops every dev server nobody is using
- Apps quit the way ⌘Q quits them, so they can ask to save
- Every quit is logged in Settings → Integrations

## Install it

### From the app

Settings → Integrations → Let AI Assistants Ask Vitals. The Terminal section there says where the command is.

```sh
vitals version
```

### With Homebrew

The app and the command together, with the manual page and tab completion for zsh, bash and fish.

```sh
brew install --cask foredotstudio/tap/vitals
```

## Every command

| Command | What it answers |
| --- | --- |
| `vitals status [<part>…]` | CPU, memory, GPU, Neural Engine, disk, network, battery, power and heat, a line each; or only the parts you name |
| `vitals top [<by>] [<period>] [N]` | The apps using the most memory, CPU, power, disk or network, now or over an hour, a day, a week, a month, a quarter, half a year or a year |
| `vitals app <name>` | One app: its processes, ports, projects and containers, and what it used over a period |
| `vitals find <name\|pid\|:port>` | A process by name, PID or port |
| `vitals ports [<port>…]` | What is listening on which port, with its process, app and project, and whether it is open to this Mac or the network |
| `vitals projects [<name>]` | Project folders with something running, their ports, memory and CPU, and dev servers nobody is using |
| `vitals containers [<name>]` | Running containers in Docker, OrbStack, Podman or Colima, with their memory, CPU, network and ports |
| `vitals agents [<name>]` | Coding agents running right now: each session’s project, whether it is working or waiting for you, and what it started |
| `vitals limits [<tool>]` | What is left of each AI plan, when each limit resets, and whether it lasts at the rate you are going |
| `vitals awake` | What is keeping the Mac awake |
| `vitals battery` | The battery, and the apps drawing the most power |
| `vitals history [<reading>…] [<period>]` | How hard the Mac was pushed over a period, and when |
| `vitals whats-wrong` | What Vitals has noticed: apps holding the CPU or growing in memory, memory pressure, heat, and dev servers left behind |
| `vitals can-quit [<app>]` | Whether something is safe to quit, with the reason and what would stop with it. By name, --pid, --port or --project |
| `vitals quit <app>` | Quits an app after its verdict and your yes. --force ends it at once |
| `vitals stop [<name>]` | Stops one of your processes the same way, by name, --pid or --port; --idle stops every idle dev server |
| `vitals completions <shell>` | Tab completion for zsh, bash or fish |
| `vitals mcp` | Speaks MCP on standard input and output, for an AI assistant |
| `vitals help` | Every command and option |

| Option | What it does |
| --- | --- |
| `--json` | The answer as JSON, for a script |
| `--csv` | The main list as CSV, for a spreadsheet |
| `--watch` | Refreshes every two seconds until Control-C; --every N for another pace |
| `--no-color` | Plain text; NO_COLOR in the environment does the same |

## Why it matters: command line on a Mac

macOS gives the terminal `top` and `ps`. Both list processes, about a thousand of them, with no idea which app or project each belongs to, and nothing about yesterday. Finding what holds port 3000 means `lsof`, a PID, and another command to find out what that PID is.

Coding agents work in the terminal too. When one wants to know what is slowing the Mac down or what is on a port, it runs the same commands and guesses from the list.

`vitals` asks the running Vitals app instead. You get apps with their helpers counted in, projects with their ports, agents with what they started, AI plans with what is left, and up to a year of history, as a table you can read or JSON a script can parse. The command measures nothing itself, so asking costs your Mac almost nothing.

## How to use it

1. **Install it.** Turn on Let AI Assistants Ask Vitals in Settings → Integrations, and Vitals links the command onto your PATH. If the folder needs your password, an Install button asks once. With Homebrew, `brew install --cask foredotstudio/tap/vitals` installs the app and the command together.
2. **Ask.** `vitals status` for the whole Mac, `vitals top cpu day` for what used the most CPU today, `vitals ports` for what is listening, `vitals agents` for your coding agents, `vitals limits` for your AI plans. `vitals help` lists every command, and `man vitals` explains each one.
3. **Script it.** Add `--json` to any command and pipe it to `jq`, or `--csv` for a spreadsheet. `--watch` refreshes the answer every two seconds until you press Control-C.
4. **Stop what you don’t need.** `vitals can-quit --port 3000` says what holds the port and whether it is safe to stop. `vitals stop --port 3000` stops it after your yes, and `vitals stop --idle` stops every dev server nobody is using.

## Compared with Activity Monitor

| | Activity Monitor | Vitals |
| --- | --- | --- |
| In Terminal | `top` and `ps`, a process per row | `vitals`, an app per row, helpers counted in |
| Ports | `lsof`, then look up the PID | `vitals ports`, with the project and who can reach it |
| Coding agents and AI plans | Nothing | `vitals agents` and `vitals limits` |
| The past | Nothing | `vitals history` and `vitals top`, for up to a year |
| For scripts | Text to parse | JSON and CSV from every command |
| Stopping something | `kill`, no questions asked | A verdict first, then your yes |

## The words behind it

- [Listening port](https://vitalsmac.com/glossary/listening-port): A listening port is a network port where a process is waiting for incoming connections, such as a web server on port 3000.
- [PID](https://vitalsmac.com/glossary/pid): A PID, or process ID, is a number macOS assigns to each running process to identify it.
- [Helper processes](https://vitalsmac.com/glossary/helper-processes): Helper processes are separate processes an app starts to do part of its work, such as rendering web pages, running extensions, or handling graphics.
- [Force Quit](https://vitalsmac.com/glossary/force-quit): Force Quit ends an app or process immediately, without letting it save or clean up.

## Questions

### Does Vitals have to be running?

Yes. The command asks the running app, which already keeps the readings and the history, so asking costs your Mac almost nothing. If Vitals isn't running, or Let AI Assistants Ask Vitals is off, the command says so and what to do.

### How do I install it with Homebrew?

Run `brew install --cask foredotstudio/tap/vitals`. It installs the app and links the `vitals` command, its manual page and tab completion for zsh, bash and fish. Vitals updates itself, so brew upgrade leaves it alone.

### I already have Vitals. How do I get the command?

Turn on Let AI Assistants Ask Vitals in Settings → Integrations. Vitals links `vitals` onto your PATH, in `/opt/homebrew/bin` or `/usr/local/bin`, and the Terminal section there says where. If the folder needs your password, an Install button asks for it once.

### Can an AI agent use it?

Yes. An agent with a shell can run `vitals` and read the answer, and in a pipe nothing is cut short. It cannot stop anything that needs a person: without a terminal to ask on, those are refused, even with `--yes`.

### How is it different from the MCP server?

It is the same connection to the app, with the same answers. The command adds quit and stop, which ask you on the terminal. An assistant speaking MCP asks through Vitals' own window instead, and `vitals mcp` is that server.

### Does it work with the free trial?

Yes. Everything in Vitals works during the trial, the command included.

### Which shells get tab completion?

zsh, bash and fish, with app names completed from what is running. Vitals installs zsh's and fish's with the command. For bash, add `eval "$(vitals completions bash)"` to your `.bashrc`; Homebrew installs all three.

## Read on

- [htop for Mac: how to install it, and the 5 best alternatives](https://vitalsmac.com/htop-for-mac)
- [Claude Code using too much memory or CPU on a Mac? How to find it, and get it back](https://vitalsmac.com/claude-code-memory-usage-mac)
- [Vitals vs Activity Monitor](https://vitalsmac.com/vs/activity-monitor)
- [Vitals vs btop](https://vitalsmac.com/vs/btop)

## More of Vitals

Every feature is at [vitalsmac.com/features](https://vitalsmac.com/features). Vitals is paid once, with a year of updates or every update for life: [pricing](https://vitalsmac.com/pricing).