Exit codes

The six exit codes every Kalup command uses, when each happens and how a script or agent should react.

Every Kalup command ends with one of six exit codes. They are fixed: a script can branch on them without reading any text. Check the exit code first, then read the JSON envelope for details.

Code	Name	Meaning
0	Done	The command did what was asked. There may be warnings.
1	Error	Something went wrong that is not about your config: no project, a bad flag, a network or HubSpot error.
2	Differences	Only with `--exit-code`: the command found changes to make. Not a failure.
3	Invalid	The config files are invalid. Nothing was written.
4	Person needed	Nothing can go on until a person acts, for example a key that belongs to the wrong portal.
5	Partial	Reserved for `apply`, which is not built yet: some writes succeeded and some did not.

When each happens

0: done

The command finished. Warnings, if any, are in issues with codes starting W_, and ok is true.

Every command can exit 0.

Code	Cause
`E_NO_CONFIG`	No `kalup.config.ts` in this directory or any above it.
`E_USAGE`	An unknown command or flag, a flag without its value, or an unexpected argument.
`E_NOT_IMPLEMENTED`	A command this version does not have yet.
`E_MISSING_KEY`, `E_AUTH`, `E_SCOPE`	The read key is missing, rejected, or lacks a scope.
`E_HTTP`, `E_UNREACHABLE`, `E_RATE_LIMIT`, `E_DAILY_LIMIT`	HubSpot answered with an error, did not answer, kept rate-limiting, or the daily API limit is used up.
`E_UNEXPECTED`	Anything else. The message is one cleaned line.

2: differences

Only with --exit-code, and only together with --check. It means "there is work to do", so CI can fail a job on it. ok is still true.

Command	Exits 2 when
`kalup fmt --check --exit-code`	A file is not in canonical form.
`kalup pull --check --exit-code`	The portal has changes the files do not have yet.

Without --exit-code, the same situations exit 0.

3: invalid

The config files break the grammar or a rule. Nothing was written. The issues name the file, the line and the fix.

validate, ir, fmt, pull and status exit 3 on an invalid config.

Kalup stopped because only a person can decide. The issue has humanRequired: true. Today this happens when the key belongs to a different portal than the one pinned for the target (E_TARGET_PORTAL_MISMATCH): init, pull and status stop before reading anything.

Changing the pinned portalId to make the mismatch go away is never the fix. Someone has to check which key and which portal are right.

5: partial

Belongs to apply, which writes to a portal. apply is not in this version, so no command exits 5 today.

How to react

Code	A script or CI job	An AI agent
0	Go on.	Go on. Mention any `W_` warnings to the user.
1	Fail the step and show the issues.	Read the issue's `fix`. If it is about keys or network, tell the user; do not retry in a loop.
2	Fail the check step, or run the command without `--check` to apply the changes locally.	Run the same command without `--check` if the user wants the change, then validate.
3	Fail the step.	Apply each issue's `fix` to the named file and line, then run `kalup validate --json` again.
4	Fail and ask a person to look.	Stop. Show the user the issue text and wait. Do not change the config to get past it.
5	Run `plan` again and review.	Stop and tell the user. Do not retry the write.

In a shell

npx kalup validate --json > result.json
case $? in
  0) echo "valid" ;;
  3) echo "invalid config, see result.json"; exit 1 ;;
  *) echo "kalup failed, see result.json"; exit 1 ;;
esac