Automation and scripting

Environment variables

Two variables cover most automation:

• IDAPT_API_KEY: the API key to authenticate with. Set it from a CI secret. See CLI authentication.

• IDAPT_API_URL: the base URL, default https://idapt.app. Change it only to target another environment.

For the workspace a script runs against, pin it once with idapt workspace use <workspace-id>or pass --workspace-id per command. There is no IDAPT_PROJECT variable.

Capture ids and structured input

Use -o quiet to capture an id, and --json to pass input that a shell would otherwise mangle:

#!/bin/bash
set -euo pipefail

# Create an agent and capture its id
AGENT_ID=$(idapt agent create --json @agent.json -o quiet)
echo "created agent: $AGENT_ID"

# Send a message on a chat
idapt chat send --id "$CHAT_ID" \
  --json '{"content":"What is the deploy status?"}' -o json | jq -r '.message.content'

Handle success and failure

The CLI maps the failure kind onto a structured exit code, so a script can branch without parsing stderr: 0 success, 1 generic error, 2 authentication (sign in again), 3 forbidden (retrying will not help), 4 not found, 5 payment or quota required, 6 a bad argument or a rejected request, 7 rate limited (back off), 8 service unavailable (retryable). The JSON error.type is still there when you need the finer reason:

if ! OUT=$(idapt chat send --id "$CHAT_ID" \
  --json '{"content":"hi"}' -o json 2>err.json); then
  TYPE=$(jq -r '.error.type // "unknown"' err.json)
  echo "send failed: $TYPE"
  exit 1
fi

Batch input

Loop a file of JSON payloads through a create command:

# One JSON object per line
while IFS= read -r line; do
  printf '%s' "$line" | idapt agent create --json -
done < agents.jsonl

# Upload every PDF in a directory
for f in ./reports/*.pdf; do
  idapt drive upload --file "$f"
done

CI/CD

A GitHub Actions step, authenticating from a secret:

- name: Install the idapt CLI
  run: npm i -g @idapt/cli

- name: Notify the team
  env:
    IDAPT_API_KEY: ${{ credentials.IDAPT_API_KEY }}
  run: |
    idapt workspace use ${{ vars.IDAPT_WORKSPACE_ID }}
    idapt chat send --id ${{ vars.IDAPT_CHAT_ID }} \
      --json '{"content":"CI finished on main"}'