Overview

codz is the Codz app’s own command-line interface. It reads the same local data as the app, with the same collectors and billing rules, and prints it in your terminal: the agents working right now, your plan limits, usage for a day, local development servers and a check of what Codz can read.

It prints plain text by default and stable JSON with --json, so scripts, status bars and automations can use it too. It reads your agents’ data directly, so it works whether or not the Codz app is open.

Set up the codz command

codz is the Codz app’s own binary, so there is nothing extra to download. Downloading Codz does not add the command to your shell, though: link it into a folder on your PATH once.

1. Make sure Codz is in your Applications folder.

2. Create the link:

   mkdir -p ~/.local/bin
   ln -s /Applications/Codz.app/Contents/MacOS/Codz ~/.local/bin/codz

   Copy

3. If your shell does not already include ~/.local/bin, add it to your PATH. For zsh, the Mac’s default shell:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

   Copy

4. Open a new terminal window and run codz doctor to check it works.

If you keep Codz somewhere else, change the first path in step 2 to match. Keep it a link rather than a copy: the command reads your Pro status from the Codz app next to it, and a copied binary cannot.

You can also run the binary directly with a command, without a link:

/Applications/Codz.app/Contents/MacOS/Codz status

Quick examples

codz                         # complete local snapshot
codz agents --json           # live agents for scripts and automations
codz usage --day 2026-08-10  # one local calendar day (Pro)
codz ports --all             # every local TCP listener
codz doctor                  # data access and provider CLI checks

Running codz with no command is the same as codz status. codz help lists every command and option, and Commands documents each one.

What needs Pro

• codz usage needs Pro. Without it, the command prints this message and exits with code 3:

  codz: Token and cost history is part of Codz Pro. Sign in to Codz in Settings ▸ Account.

  Copy

• codz status still runs without Pro. Its usage section shows the same sentence in place of your tokens, and in JSON usage is empty and usage_locked is true.

• Agents, plan limits, ports, doctor and version never need Pro.

codz never signs in on its own. It uses the answer the Codz app last recorded, so after you subscribe, open Codz and check that Settings ▸ Account shows your Pro plan. See Plans & pricing.

JSON output

Add --json to any command except help for machine-readable output. Every JSON response carries "schema_version": 1 and the name of the command that produced it. Within schema version 1, fields keep their names and meanings; new fields may be added. A field with no value is null rather than missing.

Codz never invents numbers to fill a gap. When Cursor’s account usage is unavailable, its entry is marked "fidelity": "contextOnly" and carries no token or cost total. See Commands for every field.

Exit codes

Errors go to standard error, so --json output on standard output stays valid JSON.

Compatibility

The original form, Codz --dump [--day YYYY-MM-DD], still works. It runs the app binary directly and prints the same snapshot as codz status.

Troubleshooting

The shell says command not found: codz. The link is missing or ~/.local/bin is not on your PATH. Repeat the steps in Set up the codz command, then open a new terminal window.

codz usage exits with code 3 on a Pro account. Open Codz, check that Settings ▸ Account shows your Pro plan, then run the command again. Make sure codz is a link to the app, not a copy.

Usage looks empty. Run codz doctor. It shows which agent data codz can read and where each provider’s command-line tool was found. See Troubleshooting.