CLI

Cortex does not require a separate installed CLI for normal use. The production automation path is the HTTPS API, so command-line workflows usually use curl, shell scripts, or your own CI job.

Use command-line automation when you already have a brand with a ready signature and you want to score candidates from an asset pipeline.

Environment

Keep workspace credentials outside your repository:

export CORTEX_TOKEN="ctx_live_..."
export CORTEX_BASE_URL="https://app.cortex.ad"
export BRAND_ID="brand_..."

If your team uses a secrets manager, inject these values at runtime. Do not commit tokens or generated upload URLs. Upload URLs are temporary and should be treated as sensitive while active.

Upload a candidate

Create an upload reservation:

UPLOAD_KEY="$(uuidgen)"

curl -sS -X POST "$CORTEX_BASE_URL/api/uploads/create" \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $UPLOAD_KEY" \
  -d '{
    "brand_id": "'"$BRAND_ID"'",
    "original_filename": "candidate.mp4",
    "mime_type_hint": "video/mp4",
    "size_bytes_hint": 12800000,
    "purpose": "candidate"
  }'

Upload the bytes to the returned uploadUrl, then complete the upload with the returned video_id:

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary "@candidate.mp4"

curl -sS -X POST "$CORTEX_BASE_URL/api/uploads/complete" \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $UPLOAD_KEY" \
  -d '{"video_id":"'"$VIDEO_ID"'"}'

Score the candidate

Use a new idempotency key for the scoring request:

curl -sS -X POST "$CORTEX_BASE_URL/api/scorings/create" \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"video_id":"'"$VIDEO_ID"'"}'

202 Accepted means the scoring job was created. Save the returned scoring_id. If you receive 409 with idempotency_key_in_flight, retry the same request after the Retry-After interval.

Script guidelines

• Generate an Idempotency-Key per logical operation and reuse it only when retrying that same operation.
• Store the returned video_id, scoring_id, and job_id in your system of record.
• Treat 402, 422, and 409 as product-state errors, not transient network errors.
• Retry 429 only after the Retry-After value.
• Do not parallelize signature builds for the same brand. Start one build and let it finish before starting another.

For first-time brand setup, use the browser. It is easier to review references, adjust weights, inspect calibration, and decide whether a bank is ready for automated scoring.