# Automate with the CLI (/docs/cli/automation)



Use the CLI in CI or an agent runtime when the job needs the same workspace permissions and data as an interactive customer.

## Authentication [#authentication]

Provide a short-lived, workspace-bound Invokeable access token:

```sh
export INVOKEABLE_ACCESS_TOKEN="..."
ivk --json status
```

Optional environment values include:

| Variable                     | Purpose                                                  |
| ---------------------------- | -------------------------------------------------------- |
| `INVOKEABLE_ACCESS_TOKEN`    | Short-lived access token                                 |
| `INVOKEABLE_REFRESH_TOKEN`   | Refresh token when the automation policy permits it      |
| `INVOKEABLE_ORGANIZATION_ID` | Organization context for an environment-provided session |
| `INVOKEABLE_PROFILE`         | `production` or `staging`                                |
| `INVOKEABLE_CONFIG_DIR`      | Isolated configuration directory                         |

Do not print tokens, commit them, or include them in structured command input.

## Reliable command pattern [#reliable-command-pattern]

```sh
set -euo pipefail

result="$(ivk --json j run jny_example --wait)"
printf '%s\n' "$result" | jq -e '.ok == true'
```

Check the command exit status and the documented result field. Do not treat nonempty output as success.

## Idempotency [#idempotency]

For write commands that accept `requestId`, provide a stable value when retrying the same intended operation:

```json title="input.json"
{
  "requestId": "journey_run_ci_1842",
  "journeyPublicId": "jny_example"
}
```

Do not reuse that request ID for a different action or customer intent.

## Production and staging [#production-and-staging]

Production is the default. Staging keeps separate endpoint configuration and credentials:

```sh
ivk --profile staging status
ivk --profile staging whoami
```

Use staging only with an approved staging release and staging workspace. A profile changes the CLI connection, not the semantics of a customer command.

## Safe failure handling [#safe-failure-handling]

* Preserve the nonzero exit code.
* Log the stable error code and customer-safe message.
* Retry only when the operation is known to be safe or uses a stable request ID.
* Check current state before retrying a state-changing action after a timeout.
* Stop automation when evidence is missing or a result is indeterminate.

See [Structured input and output](/docs/cli/input-and-output) and [CLI troubleshooting](/docs/cli/troubleshooting).