About utels-project-bootstrap
A bootstrap guide for registering utels.dev production and staging projects and setting Cloudflare Worker secrets. It passes ingest tokens through stdin rather than command arguments, temporary files, or logs.
Key features
- 01Register production and staging utels projects
- 02Write tokens to Worker secrets through stdin
- 03Support single-environment runs and DRY_RUN
- 04Handle registration collisions and recovery
- 05Test the flow with mocked operations
Use cases
- 01Set up utels telemetry for a Cloudflare Worker
- 02Pass project ingest tokens securely
- 03Retry registration for one environment
- 04Test registration and secret writes without remote changes
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/utels-project-bootstrapin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
README.mdassets/scripts/setup-utels.test.tssetup-utels.tsDetails
From the project READMEutels project bootstrap
Register production/staging utels.dev projects and send each returned ingest token to pnpm exec cf workers secrets update UTELS_INGEST_TOKEN --worker <name> --body @/dev/stdin. The JSON body travels through stdin on macOS/Linux; the token is not placed in argv, a temporary file or command logs.
Helper
Copy setup-utels.ts to the Worker's scripts/ directory. Use Node.js 24+ with a project-local cf dependency. The checked implementation targets cf beta.5; verify cf schema workers secrets update and the installed implementation when upgrading.
Inputs:
| Input | Purpose |
|---|---|
UTELS_BOOTSTRAP_TOKEN | Required registration credential, normally decrypted by dotenvx |
APP_WORKER_PROD / APP_WORKER_STAGING | Required Worker names for each selected target; cf resource commands do not use old --env selection |
APP_SERVER_DIR | Worker project directory; defaults to the parent of the copied script directory |
APP_UTELS_PROJECT_PROD / APP_UTELS_PROJECT_STAGING | Project slugs; replace the example defaults |
UTELS_ENDPOINT / --endpoint=<url> | Registration host, default https://utels.dev |
--only=production / --only=staging | Register just one environment, including retries after a partial failure |
DRY_RUN=1 | Skip registration and secret writes |
Customize display names and origin URLs in targets before use. utels validates origins even for server-side projects. Provide cf authentication with CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, including through an explicitly selected dotenvx file.
The helper uses --body @/dev/stdin, not --text "$TOKEN" or @-. It ignores child output because API errors can contain request bodies; on failure it reports cf's exit status. Inspect authentication separately with cf auth whoami. A registered slug can remain after a failed secret write; registration is not guaranteed idempotent and the helper does not delete projects automatically.
Registration collision
A previously registered slug can trigger a D1 unique-constraint error, exposed as HTTP 500 / Worker 1101. Query the utels database by ID before retrying:
pnpm exec cf d1 query DATABASE_ID --sql "SELECT project_id FROM project WHERE project_id LIKE '<your-slug>%';"
Choose another slug or recover the existing token through the operator's supported procedure. Destructive deletion is not part of bootstrap.
Validation and related guidance
The integration test mocks utels registration and the pnpm child to verify Worker selection, stdin JSON, failed writes and token-free output without remote mutations.
- Cloudflare telemetry: configure the returned ingest token as a Worker binding.
- cf API guide: secrets and command discovery.
- Original helper: registration protocol source; this version adapts secret delivery to cf.