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, a STANDARD account counts as protected, 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.
   • State: reports whether .kalup/state/<target>.json exists. This version never reads it, so the last apply is always never.
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)
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
  State: none. Last apply: never
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
  State: none. Last apply: never

A target that did not get past the key or the portal check is one line:

Target production: HUBSPOT_PROD_READ_KEY is not set.
Target staging: unreachable, fetch failed

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 } },
    "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": "none"
      },
      {
        "name": "production",
        "portalId": 2222222,
        "keyVariable": "HUBSPOT_PROD_READ_KEY",
        "check": "missing-key",
        "reason": "HUBSPOT_PROD_READ_KEY is not set.",
        "scopes": [],
        "state": "none"
      }
    ]
  },
  "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:

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.