@skedulo/plugin-seedr

Seed data into a Skedulo tenant from a single JSON manifest — with $ref/$lookup resolution, matchOn upserts, picklist-aware validation, batching, and automatic rollback.

Adds the sked seedr create command to the Skedulo CLI. Full docs live in the wiki.

Key features

• 🚀 Upsert-friendly loads — matchOn keys update what’s there instead of cloning duplicates.
• 🔗 Smart links — $ref wires records together, auto-ordering them and blocking cycles before they run.
• 🧭 $lookup helper — bind to records already on the tenant by field value, instead of recreating them.
• 🎯 Picklist-safe — checks enum values against the live vocabulary (picklist options).
• 🛡️ Safe by design — any failure rolls back created records, so no half-broken data is left behind.
• 👀 Preview-first — --dry-run plus --validate show the plan and errors before touching your tenant.
• 🕰️ Timezone-smart — date/time macros with real IANA zones and DST, so schedules land correctly.
• ⚡ Faster loads — batches eligible inserts (up to ~200) to shrink round-trips.
• 🤖 CI-ready — non-interactive mode, clear errors, and warnings when a check is skipped.

$ sked seedr create -f demo.json -a acme --validate --dry-run
Loaded 5 records from demo.json
Authenticated as: [email protected]  ·  Tenant: acme  ·  Environment: prod
Validating against GraphQL schema...
✓ 5 records validated against schema

=== Dry Run Plan ===
Effective date: 2026-07-03T00:00:00.000Z
Total records: 5
  [1] [create] Regions        (north)
  [2] [upsert] Accounts       (acme)     ← matchOn: Name
  [3] [create] Contacts       (jane)     ← AccountId $ref:acme
  [4] [create] Jobs           (job-1)    ← RegionId $lookup:Regions:Name:North
  [5] [create] JobAllocations (alloc-1)

$ sked seedr create -f demo.json -a acme --validate
Creating [████████████████████] 100% | 5/5 records | ✓ Created JobAllocations (alloc-1)

=== Create Summary ===
Created: 4   Updated: 1   Skipped: 0   Failed: 0

Requirements

• Skedulo CLI >= 1.0.0
• Node.js >= 18
• Access (and a logged-in session) to a Skedulo tenant

Installation

sked plugins install @skedulo/plugin-seedr

Quick start

1. Write a manifest (data.json):

{
  "records": [
    { "type": "Accounts", "localId": "acme", "fields": { "Name": "ACME" }, "matchOn": ["Name"] },
    {
      "type": "Contacts",
      "localId": "jane",
      "fields": {
        "FullName": "Jane Doe",
        "AccountId": "$ref:acme",
        "RegionId": "$lookup:Regions:Name:Charleston"
      }
    }
  ]
}

2. Preview + validate (never skip this):

sked seedr create -f data.json -a my-tenant --validate --dry-run

3. Apply (add -y/--skipUserChecks in CI):

sked seedr create -f data.json -a my-tenant --validate

If you hit User not found by alias or a token error, run sked tenant login -a my-tenant first.

Manifest at a glance

| Field | Required | Purpose | | ----------- | -------- | -------------------------------------------------------------------------- | | type | yes | Exact Skedulo object name (e.g. Accounts, Contacts, Jobs). | | localId | yes | Unique id within the file; target of $ref. | | fields | yes | At least one field. Skedulo fields are PascalCase; references end in Id. | | matchOn | no | Natural-key fields that make re-runs idempotent (upsert vs duplicate). | | dependsOn | no | Rarely needed — $ref already drives ordering automatically. |

References

• $ref:<localId> — link to another record in this manifest (drives ordering).
• $lookup:Object:Field:Value — bind to a record already on the tenant (first match wins; errors if none).

Date macros — Today, Today(+N), TodayTime, TodayTime(+N)@HH:MM@IANA_Zone (converted to UTC, DST-aware).

Batch manifests — split a large seed across files. Point -f at a manifest and all files load in one run, with $ref/dependsOn resolving across files:

{ "version": "1.0", "batch": true, "files": ["regions.json", "contacts.json", "jobs.json"] }

See the wiki for the full schema, batch manifests, lookup syntax, date macros, and troubleshooting.

Flags

| Flag | Alias | Description | | ------------------ | ----- | --------------------------------------------------------------- | | --file | -f | Path to the manifest (required). | | --alias | -a | Tenant alias (or set SKED_ALIAS). | | --validate | -v | Validate fields + picklists against the live schema/vocabulary. | | --dry-run | -d | Preview the plan without sending any mutations. | | --skipUserChecks | -y | Skip the confirmation prompt (for CI/non-interactive use). |

Development

git clone https://github.com/Skedulo/skedulo-plugin-seedr.git
cd skedulo-plugin-seedr
npm install

npm run build        # tsc -b
npm test             # vitest run
npm run test:coverage
npm run lint         # eslint (flat config)
npm run typecheck    # tsc --noEmit
npm run format       # prettier --write

CI/CD

• ci.yml — lint, typecheck, build, and test (with coverage) on every push to main and every PR, across Node 20 and 22.
• release-publish.yml — publishes a patch release (npm publish + git tag + GitHub release) only when a PR merges to main; open PRs publish nothing. Uses npm Trusted Publishing (OIDC) — no long-lived publish token; see .github/PUBLISHING.md.

Using with AI agents

This repo ships a seedr skill and an AI onboarding guide so coding agents can author and run manifests correctly (lookup-vs-create judgment, validation-first workflow, and platform gotchas).

Installing the skill

The skill is separate from the CLI plugin: the plugin runs sked seedr create, the skill just helps AI agents author manifests. Installing it is optional.

• Working inside this repo — no install needed. The skill is symlinked into .claude/skills/seedr, so Claude Code discovers it automatically.

• Anywhere else — copy it into a skills directory Claude Code reads:

  # all your projects
  git clone https://github.com/Skedulo/skedulo-plugin-seedr.git
  mkdir -p ~/.claude/skills
  cp -r skedulo-plugin-seedr/skills/seedr ~/.claude/skills/
  
  # or a single project
  mkdir -p <your-repo>/.claude/skills
  cp -r skedulo-plugin-seedr/skills/seedr <your-repo>/.claude/skills/

  It's picked up on next launch — invoke with /seedr or let it auto-activate on seed-data tasks.

Contributing

Issues and PRs are welcome — see CONTRIBUTING.md.

License

MIT © Skedulo