Commands

This is the reference for the codz command. To install it and see what it is for, start with the Overview.

codz [command] [options]

Running codz with no command is the same as codz status.

Commands

Options

--day takes an exact date such as 2026-08-10 and reads it in your Mac’s time zone. It changes only the usage figures; agents, plan meters and ports are always read as they are now.

An option on a command that does not take it is an error:

$ codz agents --all
codz: --all is not supported by 'codz agents'.
Run 'codz help' for usage.

Exit codes

On exit code 2, codz prints one of these to standard error, followed by Run 'codz help' for usage.:

On exit code 3, it prints codz: Token and cost history is part of Codz Pro. Sign in to Codz in Settings ▸ Account. See What needs Pro.

codz status

A complete snapshot of this Mac, in this order:

• the usage day
• how many agents are working, how many sessions are open for Claude, Cursor and Codex, the plan meters, and each working agent with its model and folder
• usage for the day, as codz usage prints it, or the Pro message when usage is locked
• local development ports, as codz ports prints them (every listener with --all)
• Agent memory: what your agents are holding in memory, grouped by kind, with how much could be reclaimed

With --json, status prints the fields of agents, usage and ports together in one object. It does not include agent memory.

codz agents

The agents working right now, the sessions open for each provider, and your plan meters: Claude’s 5-hour, 7-day and extra usage, and Codex’s windows with their reset times.

{
  "agents": [
    {
      "context_limit": null,
      "context_used": null,
      "cwd": "/Users/you/Projects/storefront",
      "detail": null,
      "id": "claude:0b4f6e2a-5c1d-4f7e-9a3b-8d2c1e6f4a90",
      "model": "claude-haiku-4-5-20251001",
      "name": "Fix the login redirect",
      "platform": "claude",
      "started_at": "2026-09-29T14:02:11.482Z",
      "status": "working"
    }
  ],
  "command": "agents",
  "generated_at": "2026-09-29T14:05:37.918Z",
  "open": {
    "claude": 2,
    "codex": 1,
    "cursor": 0,
    "deepseek": 0,
    "opencode": 0,
    "openrouter": 0
  },
  "plans": {
    "claude": {
      "extra_percent": null,
      "five_hour_percent": 38,
      "seven_day_percent": 12
    },
    "codex": [
      {
        "account": null,
        "account_id": null,
        "limit_id": "codex",
        "limit_name": null,
        "measured_at": "2026-09-29T13:58:40.000Z",
        "plan_type": "plus",
        "windows": [
          {
            "resets_at": "2026-09-29T17:10:00.000Z",
            "used_percent": 21,
            "window_minutes": 300
          },
          {
            "resets_at": "2026-10-03T09:00:00.000Z",
            "used_percent": 7,
            "window_minutes": 10080
          }
        ]
      }
    ],
    "cursor": {
      "cycle_percent": null,
      "included_spend_cents": null,
      "limit_cents": null,
      "message": null,
      "remaining_cents": null
    }
  },
  "schema_version": 1,
  "working": 1
}

• working is the number of entries in agents. open counts open sessions per provider.
• plans.codex has one entry per Codex login and limit pool; account names the login when there is more than one.
• plans.cursor is read only by status. In agents its fields are always null.

codz usage

Token usage for one local calendar day: an estimated total, then one line per provider with its billable tokens, its estimated cost and where the cost comes from, followed by its top models and their token buckets.

cost_source is null when no cost can be stood behind. Cursor’s tokens come from its account usage API; when that is unavailable, Cursor is listed as Cursor — Context only (account tokens unavailable), with its sessions’ context fill instead of totals.

{
  "command": "usage",
  "day": "2026-09-29",
  "generated_at": "2026-09-29T18:20:04.512Z",
  "schema_version": 1,
  "usage": [
    {
      "billable_total": 1282000,
      "context": [],
      "cost_source": "api_list_price_estimate",
      "estimated_raw_cost_usd": 3.05,
      "fidelity": "billable",
      "models": [
        {
          "estimated_raw_cost_usd": 3.05,
          "model": "gpt-5.5",
          "tokens": {
            "billable_total": 1282000,
            "cache_read": 980000,
            "cache_write": 0,
            "input": 1240000,
            "output": 42000,
            "reasoning": 18000
          }
        }
      ],
      "platform": "codex",
      "tokens": {
        "billable_total": 1282000,
        "cache_read": 980000,
        "cache_write": 0,
        "input": 1240000,
        "output": 42000,
        "reasoning": 18000
      }
    }
  ],
  "usage_locked": false
}

• usage has one entry per provider with activity that day.
• fidelity is billable, or contextOnly for Cursor without account data. A contextOnly entry has no token or cost totals, and context lists the live sessions with context_used and context_limit.
• billable_total follows each provider’s billing. Codex and OpenRouter count cached input inside input and reasoning inside output, so their total is input plus output. Claude, Cursor, OpenCode and DeepSeek report the five buckets separately, so theirs is the sum of all five.
• usage_locked is true when usage is empty because the Mac is not on Pro. You see it from codz status --json.

codz ports

The local development servers on this Mac: the port, the project it belongs to, the process and its PID. Databases, debuggers and system services are left out unless you add --all, which lists every TCP listener. Ports are the same list the Ports page shows.

{
  "command": "ports",
  "generated_at": "2026-09-29T14:06:02.311Z",
  "port_filter": "development",
  "port_scan_error": null,
  "ports": [
    {
      "address": "127.0.0.1",
      "command": "node",
      "cwd": "/Users/you/Projects/storefront",
      "display_command": "Node.js",
      "is_likely_development": true,
      "pid": 48213,
      "port": 3000,
      "project": "storefront",
      "scope": "local",
      "url": "http://localhost:3000"
    }
  ],
  "schema_version": 1
}

• port_filter is development, or all with --all.
• scope is local for a listener only this Mac can reach, or all_interfaces.
• port_scan_error says why the scan failed, when it did.

codz doctor

Checks what codz can read and which provider tools it can find. The same checks run in the app’s setup.

Codz doctor
  [ok] Claude data: Readable · /Users/you/.claude
  [warn] Cursor data: Not found or unreadable · /Users/you/Library/Application Support/Cursor/User/globalStorage/state.vscdb
  [ok] Codex data: Readable · /Users/you/.codex
  [ok] Claude CLI: Installed · /Users/you/.local/bin/claude
  [warn] Cursor CLI: Not installed
  [ok] Codex CLI: Installed · /opt/homebrew/bin/codex
  [ok] Port discovery: Available · /usr/sbin/lsof

Warnings are expected for providers you do not use.

With --json, each check is an object in checks, in the same order:

{
  "check": "Claude data",
  "detail": "Readable",
  "path": "/Users/you/.claude",
  "status": "ok"
}

status is ok or warning, and path is null when there is nothing to point at. The response also carries command, generated_at and schema_version.

“Found, but macOS blocked the read” means the data is there but macOS refused access. codz doctor checks from the terminal you run it in; if it reads your data but the app shows zeros, give the Codz app Full Disk Access. See Troubleshooting.

codz version

Prints the version, the build number and the commit it was built from:

codz 0.1.0 (212, 84bcd8839cc6)

{
  "build": "212",
  "command": "version",
  "commit": "84bcd8839cc6",
  "schema_version": 1,
  "version": "0.1.0"
}

Your numbers will differ. Include this line when you contact support.

JSON output

Every command except help takes --json. The response is one JSON object:

• Keys are sorted alphabetically, and a field with no value is null rather than missing.
• Times such as generated_at, started_at and resets_at are ISO 8601 in UTC with fractional seconds.
• Percentages are numbers from 0 to 100, costs are US dollars, and Cursor’s plan amounts are in cents.
• Within schema version 1, fields keep their names and meanings; new fields may be added.

Compatibility form

Codz --dump [--day YYYY-MM-DD]

The original form runs the app binary directly and prints the same snapshot as codz status. It still works, with or without --json.