Docs / Deployments

Official CrawlDrift CLI

Validate and report a deployment from a CI runner through the canonical Deployment API.

Notify CrawlDrift

npx @crawldrift/cli deployment notify \
  --project "$CRAWLDRIFT_PROJECT_ID" \
  --version "$APP_VERSION" \
  --build "$BUILD_NUMBER" \
  --commit "$COMMIT_SHA" \
  --environment production \
  --trigger-crawl

Environment variables

CLI arguments override environment variables.

CRAWLDRIFT_API_KEY
CRAWLDRIFT_PROJECT_ID
CRAWLDRIFT_VERSION
CRAWLDRIFT_BUILD_NUMBER
CRAWLDRIFT_COMMIT_SHA
CRAWLDRIFT_ENVIRONMENT
CRAWLDRIFT_EXTERNAL_DEPLOYMENT_ID
CRAWLDRIFT_TRIGGER_CRAWL
CRAWLDRIFT_ROLLOUT_DELAY_SECONDS

Output and responsibilities

The CLI validates inputs, sends the Bearer token and an idempotency key, redacts secrets, applies a request timeout and retries only safe transport failures.

It prints a human-readable result or machine-readable JSON with --json. It does not run a crawler, wait for crawl completion, manage queues or retain local deployment state.

crawldrift deployment notify --json

{
  "deploymentId": "dep_01K...",
  "accepted": true,
  "crawlStatus": "SCHEDULED"
}

Exit codes

0  success
1  unexpected client error
2  invalid arguments
3  authentication/authorization failure
4  API validation failure
5  transport timeout/failure
6  server unavailable

Shared API contract

Fields, limits and linked crawl behavior

All official clients and compatibility examples submit the same provider-neutral Deployment API contract.

Field	Required	Limit	Purpose
version	One identity field*	100 characters	Release version
buildNumber	One identity field*	100 characters	CI build number
commitSha	One identity field*	100 characters	Commit identity
environment	Optional	50 characters	Deployment environment
externalDeploymentId	Optional	200 characters	Provider deployment identity and idempotency
deployedAt	Optional	Timestamp string	Deployment time
note	Optional	1000 characters	Deployment note
triggerCrawl	Optional	Boolean	Request a linked FULL crawl
rolloutDelaySeconds	Optional	0–3600 seconds	Wait before requesting the linked crawl

* At least one of version, buildNumber or commitSha must be present.

Rollout delay

The request value takes precedence, followed by the Project deployment default, then the platform default. The recommended platform default is 180 seconds; the client does not wait locally.

Collision and quota

An active FULL crawl is not cancelled or replaced. The linked crawl waits for it to finish. Deployment-triggered crawls consume normal crawl-page quota; without quota, the deployment remains recorded and the crawl is BLOCKED_BY_QUOTA.

Retries and timeout

Official clients use a recommended 10-second timeout and may retry network failures, connection resets, and HTTP 502, 503 or 504 with bounded exponential backoff and jitter. Reuse the same idempotency key.

Do not automatically retry most 400, 401, 403, 404, 409 semantic conflict or 422 responses. A timeout does not prove rejection.

Key security

A Deployment key can create deployment records only for its Project. It cannot read Project, Incident or Crawl data, change settings or billing, manage users, start arbitrary crawls or access another Project.

Keys are shown in full once, stored as a cryptographic hash, revocable, replaceable and excluded from logs and diagnostics.

Request limits and target safety

Recommended per-key limits are 10 requests per minute burst and 100 requests per hour sustained; exact limits may be adjusted based on usage.

The API accepts metadata, not callback or arbitrary target URLs. The Project's verified canonical domain remains the crawl target.