CLI troubleshooting

Resolve installation, configuration, sign-in, input, permission, and run-control problems.

Command not found

Confirm the package is installed and that the global package binary directory is on PATH:

ivk --version
invokeable --version

If neither command exists, reinstall from npm. Restart the shell only if the package manager changed PATH.

Invokeable is not configured

Official production releases contain production connection defaults. For a controlled custom environment, set:

ivk config set endpoint "<endpoint from Invokeable>"
ivk config set client-id "<client ID from Invokeable>"
ivk config set app-url https://app.example.com

Use only values supplied by an Invokeable administrator. Do not copy production credentials into staging.

Run:

ivk login --no-browser

Open the printed verification URL yourself and enter the code. If the code expires, run the command again. Do not reuse an expired code.

Wrong workspace

ivk ws list
ivk ws switch org_123
ivk whoami

Use the organization ID from the current list.

Validate that --input contains one JSON object. Use --field name=value for short values. The CLI reports stable codes such as INPUT_JSON_INVALID, INPUT_FIELD_INVALID, INPUT_FIELD_MISSING, and INPUT_FIELD_UNEXPECTED.

Permission denied

Run ivk access current and ivk whoami. The active role sets the maximum permission. A scoped evidence restriction or approval requirement may add another condition.

Ask an Admin for the smallest needed access. Do not switch to a more privileged token as a workaround.

A destructive action requires confirmation

Read the command and input again, then repeat with --yes only when the target is correct. The confirmation requirement protects archive, revoke, stop, remove, deactivation, and deletion operations.

A run timed out while waiting

A wait timeout does not prove that the assessment failed or stopped. Use the returned plan ID:

ivk r progress plan_example
ivk r list

Check current state before retrying any state-changing operation.

JSON output contains an error

Use the stable error code and exit status. Do not parse raw messages for control flow. Unknown failures use a safe fallback instead of exposing a provider response or stack trace.

Credential command fails

Confirm the connection is waiting for a credential and that you used its product-connection ID. The secret file must contain a nonempty value. The CLI removes one trailing newline before sealing it.

For product-level problems, see General troubleshooting.