chore(release): 2.3.0 -- configurable API-error exit code

Minor bump for the new --exit-code-on-api-error flag and the supporting
non-breaking improvements (commit-message truncation, Buildkite-aware infra
error logging, --timeout / --exclude-license-details fixes).

This release is intentionally NON-breaking: default exit codes are unchanged,
the exit code only shifts when --exit-code-on-api-error is explicitly passed,
and --disable-blocking keeps its existing precedence. The breaking exit-code
behavior change (infra errors exiting non-zero even under --disable-blocking)
is deferred to a future 3.0.

CHANGELOG + README document the flag AND its interaction with --disable-blocking
(which overrides it) to reduce user error in the Buildkite soft_fail setup.

Version refs synced across pyproject.toml, socketsecurity/__init__.py, and
uv.lock (per the version-incrementation CI check).

Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

Author: lelia

CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 2.3.0
+
+### New: `--exit-code-on-api-error`
+
+Adds a configurable exit code for API / infrastructure failures (timeouts,
+network errors, unexpected exceptions), so CI pipelines can distinguish them
+from blocking security findings (exit `1`):
+
+```
+socketcli --exit-code-on-api-error 100 ...
+```
+
+Default is `3` (the code the CLI already used for these errors), so **default
+behavior is unchanged** — the exit code only changes when you pass the flag.
+Set it to a Buildkite `soft_fail` code, or to `0` to swallow infra errors.
+
+**Interaction to be aware of:** `--disable-blocking` forces exit `0` for *all*
+outcomes and therefore overrides `--exit-code-on-api-error`. Use the new flag
+*without* `--disable-blocking` if you want a custom infra-error code to take
+effect. See the exit-code reference in the README.
+
+> A future `3.0` release is planned to make infrastructure errors exit non-zero
+> even under `--disable-blocking` (so outages stop being silently swallowed).
+> That is a breaking change and is intentionally **not** in this release.
+
+### New: commit message auto-truncation
+
+`--commit-message` values longer than 200 characters are now automatically
+truncated before being sent to the API, preventing HTTP 413 errors from
+oversized URL query parameters (common with AI-generated commit messages or
+`$BUILDKITE_MESSAGE`).
+
+### Improved: Buildkite log formatting
+
+When running inside a Buildkite job (`BUILDKITE=true`), infrastructure errors
+emit Buildkite log section markers (`^^^ +++` / `--- :warning:`) so the error
+section auto-expands in the BK UI, plus a `soft_fail` hint. No effect on other
+CI platforms.
+
+### Fixed
+
+- `--timeout` is now honored end-to-end: it was only applied to the local
+  `CliClient`, but the full-scan diff comparison uses the Socket SDK instance,
+  which was constructed without the CLI timeout and defaulted to 1200s.
+- `--exclude-license-details` now propagates to the full-scan diff comparison
+  request (it was only applied to full-scan params / report URLs before).
+
 ## 2.2.90
 
 - Migrated license enrichment PURL lookup to the org-scoped endpoint (`POST /v0/orgs/{slug}/purl`) from the deprecated global endpoint (`POST /v0/purl`).

README.md

@@ -194,6 +194,48 @@ Minimal pattern:
     SOCKET_SECURITY_API_TOKEN: ${{ secrets.SOCKET_SECURITY_API_TOKEN }}
 ```
 
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Clean scan — no blocking issues (or `--disable-blocking` set) |
+| `1`  | Blocking security finding(s) detected |
+| `2`  | Scan interrupted (SIGINT / Ctrl+C) |
+| `3`  | Infrastructure or API error (timeout, network failure, unexpected error) |
+
+`--exit-code-on-api-error <N>` remaps the infrastructure-error code (`3`) to any
+value — e.g. a Buildkite `soft_fail` code, or `0` to swallow infra errors. Exit
+`3` is a Socket convention, not an industry standard.
+
+### How these options interact
+
+The two flags that affect exit codes can cancel each other out, so the order of
+precedence matters:
+
+- **`--disable-blocking` wins over everything.** It forces exit `0` for *all*
+  outcomes — security findings *and* infrastructure errors. If you set it,
+  `--exit-code-on-api-error` has no effect (you'll always get `0`).
+- **`--exit-code-on-api-error` only applies when `--disable-blocking` is *not*
+  set.** It changes the infra-error code (and the generic-error code); it never
+  touches the security-finding code (`1`).
+
+So for the common "don't let Socket outages block my pipeline, but still fail on
+real findings" goal, use `--exit-code-on-api-error` **without** `--disable-blocking`:
+
+```yaml
+# Buildkite: soft-fail only on infrastructure errors, still block on findings
+steps:
+  - label: ":lock: Socket Security Scan"
+    command: "socketcli --exit-code-on-api-error 100 ..."   # NOT --disable-blocking
+    soft_fail:
+      - exit_status: 100
+```
+
+Combining `--disable-blocking` with `--exit-code-on-api-error 100` would make the
+scan exit `0` on *both* findings and outages — the `soft_fail: 100` rule would
+never match, and real findings would stop blocking. That's usually not what you
+want.
+
 ## Common gotchas
 
 See [`docs/troubleshooting.md`](https://github.com/SocketDev/socket-python-cli/blob/main/docs/troubleshooting.md#common-gotchas).

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.2.91"
+version = "2.3.0"
 requires-python = ">= 3.11"
 license = {"file" = "LICENSE"}
 dependencies = [

socketsecurity/__init__.py

@@ -1,3 +1,3 @@
 __author__ = 'socket.dev'
-__version__ = '2.2.91'
+__version__ = '2.3.0'
 USER_AGENT = f'SocketPythonCLI/{__version__}'