kalup status

status tells you whether a project is ready to run. It validates the config, then checks each target: is the key set, does it belong to the pinned portal, and does it hold every read scope the objects in scope need. Run it after init, after changing a key, and first when something fails.

It never writes anything, to the portal or to disk.

Usage

npx kalup status [--target <name>] [--json]

Options

What it does

1. Validates the config. An invalid config stops status with exit 3 and the first three issues. See kalup validate for the full list.
2. Checks each target in turn. A problem with one target is one line and one issue. It never stops the checks for the other targets.
   • Key: reads the variable named in credentials.read.env, or HUBSPOT_SERVICE_KEY, from the environment or .env. When it is not set, the target shows the missing variable and the other checks are skipped.
   • Portal pin: asks HubSpot which account the key belongs to, and compares it with the target's portalId. A different account is a mismatch.
   • Protected: reports whether the target is protected. When the config does not say, every account but a DEVELOPER_TEST, SANDBOX or APP_DEVELOPER one counts as protected, an unknown type included, and the output says it is the default.
   • Read scopes: sends one list request per scope the objects in scope need: one properties list per standard object, and one schemas list when any custom object is in scope. A 403 means the scope is missing. Any other failure is reported with its code. The crm.objects.<object>.read scope init recommends for plan's property limit check is printed as Also recommended, not checked: status sends no request for it. On a developer test account (2026-09-29) Limits Tracking answered 403 to a key with crm.schemas.* scopes only.
   • Write key: names the variable apply takes its key from, credentials.write or else the read key's, and the write scopes apply needs besides the read scopes. A separate write key needs the read scopes too, since apply reads with the key it writes with. None of this is checked: like every read command, status never reads or sends the write key, and HubSpot offers no scope check for service keys.
   • State: reads the state file of the pinned portal, .kalup/state/portal-<portalId>.json, and reports its path, whether it exists, its lineage and serial, and the last apply: its plan, time and outcome. A last apply still running means an apply did not finish: run kalup plan. A file that cannot be read is E_STATE_INVALID on that target. status never writes state. See kalup state.
3. Checks the API pins. When a HubSpot API version that Kalup is pinned to expires within 90 days, it warns with W_PIN_EXPIRES.

Output

kalup 0.1.0
Config: valid (3 objects, 42 properties, 5 groups) in hubspot/
Target sandbox: portal 1111111 matches, SANDBOX, app-eu1.hubspot.com, Europe/Ljubljana, protected: no
  Scopes: crm.schemas.companies.read ok, crm.schemas.deals.read ok, crm.schemas.custom.read ok
  Also recommended: crm.objects.companies.read, not checked (the property limit check in plan)
  Write: apply uses HUBSPOT_SERVICE_KEY, which also needs crm.schemas.companies.write, crm.schemas.deals.write, crm.schemas.custom.write, not checked
  State: .kalup/state/portal-1111111.json, lineage 5e1d0c7a9b3f2468, serial 7. Last apply: plan pl_0a1b2c3d4e5f at 2026-09-25T09:40:13.864Z, done
Target production: portal 2222222 matches, STANDARD, app-eu1.hubspot.com, Europe/Ljubljana, protected: yes (STANDARD account, default)
  Scopes: crm.schemas.companies.read ok, crm.schemas.deals.read missing (needed for deals), crm.schemas.custom.read ok
  Also recommended: crm.objects.companies.read, not checked (the property limit check in plan)
  Write: apply uses HUBSPOT_PROD_WRITE_KEY, which needs the read scopes and crm.schemas.companies.write, crm.schemas.deals.write, crm.schemas.custom.write, not checked
  State: none (.kalup/state/portal-2222222.json). Last apply: never

The target defaultTarget names has (defaultTarget) after its name, for example Target sandbox (defaultTarget): portal 1111111 matches, SANDBOX, app-eu1.hubspot.com, Europe/Ljubljana, protected: no.

A pending target, one with no portalId yet, is one line and its write line; nothing is checked for it and the exit code stays 0:

Target production: pending, no portalId yet; set targets.production.portalId in kalup.config.ts
  Write: apply uses HUBSPOT_SERVICE_KEY, which also needs crm.schemas.companies.write, not checked

A target that did not get past the key or the portal check is the reason and its state line:

Target production: HUBSPOT_PROD_READ_KEY is not set.
  Write: apply uses HUBSPOT_PROD_WRITE_KEY, which needs the read scopes and crm.schemas.companies.write, not checked
  State: none (.kalup/state/portal-2222222.json). Last apply: never
Target staging: unreachable, fetch failed
  Write: apply uses HUBSPOT_STAGING_KEY, which also needs crm.schemas.companies.write, not checked
  State: none (.kalup/state/portal-3333333.json). Last apply: never

A scope is ok, missing (needed for ...) after a 403, or failed (<code>) for any other failure, for example failed (E_HTTP) on a 503. With no objects in scope, the line is Scopes: none needed. The issues behind each line go to stderr, one per line, with the fix, for example (fix: Add the scope crm.schemas.deals.read to the key.).

With --json

{
  "format": "envelope/1",
  "ok": false,
  "data": {
    "config": { "valid": true, "counts": { "objects": 3, "properties": 42, "groups": 5 }, "dir": "hubspot" },
    "recommended": { "scope": "crm.objects.companies.read", "neededFor": ["the property limit check in plan"] },
    "targets": [
      {
        "name": "sandbox",
        "portalId": 1111111,
        "keyVariable": "HUBSPOT_SERVICE_KEY",
        "check": "ok",
        "account": {
          "portalId": 1111111,
          "accountType": "SANDBOX",
          "uiDomain": "app-eu1.hubspot.com",
          "timeZone": "Europe/Ljubljana"
        },
        "protected": false,
        "protectedBy": "default",
        "scopes": [
          { "scope": "crm.schemas.companies.read", "ok": true, "neededFor": ["companies"] },
          { "scope": "crm.schemas.custom.read", "ok": true, "neededFor": ["object:subscription"] }
        ],
        "state": {
          "path": "/work/orchard/.kalup/state/portal-1111111.json",
          "exists": true,
          "lineage": "5e1d0c7a9b3f2468",
          "serial": 7,
          "lastApply": { "planId": "pl_0a1b2c3d4e5f", "at": "2026-09-25T09:40:13.864Z", "outcome": "done" }
        },
        "write": { "keyVariable": "HUBSPOT_SERVICE_KEY", "separate": false }
      },
      {
        "name": "production",
        "portalId": 2222222,
        "keyVariable": "HUBSPOT_PROD_READ_KEY",
        "check": "missing-key",
        "reason": "HUBSPOT_PROD_READ_KEY is not set.",
        "scopes": [],
        "state": { "path": "/work/orchard/.kalup/state/portal-2222222.json", "exists": false },
        "write": { "keyVariable": "HUBSPOT_PROD_WRITE_KEY", "separate": true }
      }
    ],
    "writeScopes": [
      { "scope": "crm.schemas.companies.write", "neededFor": ["companies"] },
      { "scope": "crm.schemas.custom.write", "neededFor": ["subscription"] }
    ]
  },
  "issues": [
    {
      "code": "E_MISSING_KEY",
      "message": "HUBSPOT_PROD_READ_KEY is not set.",
      "fix": "Set HUBSPOT_PROD_READ_KEY in the environment or in .env in the project directory."
    }
  ]
}

Per target:

writeScopes[] lists the write scopes apply needs besides the read scopes, each with scope and neededFor. They are never checked.

ok is true only when the exit code is 0.

Exit codes

Exit 4 wins over exit 1. See Exit codes.

Errors

A config error such as E_NOT_DATA stops status with exit 3 before any request.

Examples

Check every target:

npx kalup status

Check only production:

npx kalup status --target production

For agents

• Run npx kalup status --json first when a command fails for a reason you do not understand.
• Read data.targets[].check per target. missing-key means the user has to set the variable in keyVariable. Never ask them to paste the key into the chat.
• A scope with ok: false and no error is missing from the key. Tell the user the scope name in scope. Only the key's creator can add it.
• Exit 4 means a key belongs to another portal. Stop, and tell the user which target and variable. Do not change portalId to make the check pass.
• status sends only reads and writes nothing, so it is always safe to run.