Troubleshoot Codi

Use the help generated by the installed client instead of assuming that a command or option is available:

An unknown command, missing operand, unsupported option, duplicated option, or invalid option value exits with code 2. The human-readable error is followed by the top-level usage text.

Check the selected endpoint without requiring authentication:

Confirm that the URL contains only its scheme and authority, with no path. Codi requires HTTPS unless CODINAMO_ALLOW_INSECURE_HTTP=true is explicitly configured for an isolated development environment.

If the endpoint is correct but slow, retry one diagnostic request with a timeout from 1 to 300 seconds:

An unavailable status check exits with code 1.

The message not authenticated; run 'codi auth login' means that neither the selected profile nor CODINAMO_ACCESS_TOKEN supplied a token.

HTTP 401 exits with code 3. Log in again for an interactive profile, or replace the expired CODINAMO_ACCESS_TOKEN in the CI secret store. Use --profile <name> when the credential belongs to a profile other than the active one.

Do not print a token to diagnose authentication. auth whoami verifies the credential without exposing it.

Workspace-scoped commands fail before making their main request when no workspace has been selected. Choose one persistently or override it for a single command:

workspace use stores the canonical workspace ID in the selected profile. --workspace does not alter saved profile state.

Codi resolves most resources by canonical ID or unique name. Organizations, workspaces, and teams also accept slugs; targets also accept reference names.

List the resource with --quiet, then repeat the command with its canonical ID:

A local selector failure exits with code 2. An HTTP 404 returned by the server exits with code 5.

HTTP 403 and a denied access decision both exit with code 4. Inspect the authenticated identity and the effective decision on the exact resource:

Use grant effective when diagnosing access for another user or team:

Check direct grants, parent-scope inheritance, team membership, expiration, and permission implications before creating another grant. See How access control works.

HTTP 409 or 412 exits with code 6. The resource changed after the version or revision used by the command was read.

Fetch the current role or grant, review the intervening change, update the JSON definition, and retry. Do not blindly replace expectedVersion or expectedRevision: those fields prevent one administrator from overwriting another administrator’s work.

When the version or revision field is omitted, Codi reads the current resource immediately before mutation and supplies that concurrency value automatically.

Validate a local document without changing the saved pipeline:

Validation diagnostics are printed in table or JSON form and the command exits with code 1. Correct every diagnostic before running pipeline update. If the source was piped from another command, use --file - and verify that the producer writes a complete ICE document.

See ICE syntax for the supported grammar.

Role, grant, and deployment-target definitions must be JSON objects, not arrays. Confirm the file path, JSON syntax, and required fields. To isolate filesystem issues, validate piped content through standard input:

Invalid JSON or a missing local file exits with code 2 for validated input errors or code 1 for a local I/O failure.

secret-group set never accepts a secret value as an argument. In an interactive terminal it prompts without echo. In automation, provide --stdin and pipe exactly the value:

An empty value is rejected. Avoid commands that add debugging output to the same pipe.

JSON mode is non-interactive for destructive operations. Confirm the target with a read operation, then pass --yes explicitly:

Without --yes, the command exits with code 2 and does not mutate the resource.

Use --output json when the script needs structured fields. Use --quiet only when the command documents identifier-oriented output; its minimal value varies by resource.

Keep standard output and standard error separate. A command can return a JSON error on standard error while leaving standard output empty. Always check the exit code before consuming output.

See Codi command reference for output modes and the complete exit-code table.