@koderlabs/tasks-cli

InstantTasks operator CLI: validate your install, upload source maps and native symbols, scaffold SDK init, and tail incoming events from any terminal.

Install

Run on demand without installing:

npx @koderlabs/tasks-cli doctor

Or install globally:

npm install -g @koderlabs/tasks-cli
# or
pnpm add -g @koderlabs/tasks-cli
# or
yarn global add @koderlabs/tasks-cli

tasks --help

Configuration

Every command resolves config in this order (highest precedence first):

1. CLI flag (e.g. --api-url, --key)
2. Environment variable
3. .tasksrc.json in the current directory or any ancestor
4. Built-in defaults

| Env var | Purpose | Alias accepted | |----------------------------|----------------------------------|---------------------------------| | IT_API_URL | API base URL incl. /api/v1 | IT_API_URL | | IT_INGEST_KEY | pk_ (read) or sk_ (write) | IT_MANAGEMENT_KEY | | IT_PROJECT_ID | Project UUID | |

A .tasksrc.json looks like:

{
  "endpoint": "https://tasks.koderlabs.net/api/v1",
  "ingestKey": "sk_live_xxx",
  "projectId": "00000000-0000-0000-0000-000000000000"
}

Commands

tasks doctor

Validates config + connectivity. Exits non-zero on any failure (CI-friendly).

tasks doctor

Checks:

• .tasksrc.json / env vars resolve
• GET /sdk/v1/config is reachable with the provided key
• Key role allows source-map uploads (sk_ only — pk_ keys are warned)
• IT_PROJECT_ID is set

tasks sourcemap upload <dist>

Recursively walks <dist> for *.map files, defends against path traversal/symlink escapes, then POSTs each map to /sdk/source-maps with exponential backoff on transient 5xx.

tasks sourcemap upload ./dist --release "$GIT_SHA" --environment production

Flags:

| Flag | Default | Meaning | |-------------------|------------------------|--------------------------------------------------------| | --release <sha> | none | Associate maps with a release version | | --environment | production | Environment label | | --max-size | 52428800 (50 MB) | Per-file size cap; oversized files are skipped | | --no-strict | strict on | Don't fail the run on individual file errors |

tasks symbols upload-ios <dsym>

Walks a .dSYM bundle's DWARF directory and posts each symbol file to /sdk/native-symbols.

tasks symbols upload-ios ./build/MyApp.dSYM --release "$BUILD_NUMBER"

Requires backend endpoint /sdk/native-symbols — when the endpoint is absent the CLI surfaces a warning and exits gracefully (does not fail the build) so you can wire the CLI into CI before the backend ships.

tasks symbols upload-android <mapping>

Posts a single ProGuard mapping.txt to the same /sdk/native-symbols endpoint.

tasks symbols upload-android ./android/app/build/outputs/mapping/release/mapping.txt \
  --release "$BUILD_NUMBER"

Same backend caveat as upload-ios.

tasks init <platform>

Scaffolds a .tasksrc.json template plus an init({...}) snippet appropriate to the platform. Refuses to overwrite existing files unless --force.

tasks init web        # vanilla browser
tasks init react      # CSR React app
tasks init nextjs     # writes instrumentation.ts
tasks init vue
tasks init rn         # React Native + Expo
tasks init nestjs     # backend Node

Flags:

• --dry-run — print the files that would be written but write nothing
• --force — overwrite existing files

tasks events tail

Tails recent SDK events one-per-line. Currently long-polls /sdk/v1/events?since=<ms> every 5s; intended to be swapped for a WebSocket stream once the backend ships one. Ctrl-C exits cleanly.

tasks events tail --filter project=$IT_PROJECT_ID --since 10m

Flags:

• --filter k=v ... — repeatable filter pairs
• --since <duration> — lookback window (e.g. 30s, 10m, 1h, 2d)
• --interval <ms> — poll interval (default 5000)

Requires backend endpoint /sdk/v1/events — when missing the CLI prints a clear warning and exits.

Example workflows

Verify your install

export IT_API_URL=https://tasks.koderlabs.net/api/v1
export IT_INGEST_KEY=sk_live_xxx
export IT_PROJECT_ID=00000000-0000-0000-0000-000000000000
tasks doctor

Upload source maps from CI

# .github/workflows/deploy.yml
- name: Upload source maps
  env:
    IT_API_URL: ${{ secrets.IT_API_URL }}
    IT_INGEST_KEY: ${{ secrets.INSTANTTASKS_SOURCEMAPS_KEY }}
  run: npx @koderlabs/tasks-cli sourcemap upload ./dist --release "${{ github.sha }}"

Tail events during dev

tasks events tail --since 30m --filter project=$IT_PROJECT_ID

Legacy commands

upload-sourcemaps and create-release (the original scaffold commands) are still wired and behave exactly as before. Prefer tasks sourcemap upload … for new work.

Runtime

• Node 22+ (uses native fetch)
• Zero native modules

Suite overview

Full SDK suite map + platform availability matrix: docs/sdk/overview.md.

License

KoderLabs proprietary. See LICENSE for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.

Licensing inquiries: [email protected]