Apple cktool

Use the stateless cktool CLI distributed with Xcode to manage CloudKit schemas and test data from macOS. Keep the target explicit and default all development automation to the development environment.

Choose the right companion

Use both skills when a repository exposes a simple local cktool path and a portable CKTool JS CI path. Keep the same team, container, environment, schema file, and safety policy across both implementations.

Follow the operating workflow

1. Inspect the local tool. Run:

   xcode-select -p
   xcrun --find cktool
   xcrun cktool --version
   xcrun cktool --help
   xcrun cktool help <subcommand>
   

   Treat local help as authoritative for the installed Xcode. Use man cktool for field formats, token precedence, and examples. Do not assume flags from a different Xcode release.

2. Resolve the complete target. Record the team ID, container ID, environment, database type, zone, record type, and schema path that apply. Do not infer a production target from an app bundle identifier. Use get-teams when the team ID is unknown.

3. Select the token class. Use a management token for team/container discovery and schema operations. Use a user token for record operations on behalf of an iCloud user. Read references/authentication-and-automation.md before configuring tokens or CI.

4. Prepare a reversible command. Export before schema changes, validate before import, query before a single-record deletion, and use the default dry run before bulk deletion. Treat reset, import, creation, and deletion as remote mutations.

5. Confirm destructive scope. Before a destructive operation, state the exact container, environment, database, zone, record type or record name, and expected effect. Require explicit user authorization for production writes, schema reset, or permanent deletion unless that exact operation is already the user's request.

6. Execute without exposing credentials. Prefer interactive Keychain storage for local work and environment injection from a secret manager for CI. Never print, paste into logs, commit, or pass a token in a command when a safer mechanism is available.

7. Verify the result. Check the exit status, capture structured JSON when the command returns it, re-export a changed schema, or re-query affected records. Report the resolved target and outcome, with tokens redacted.

Apply safety invariants

• Default to development. Treat any production record mutation as high impact.
• Remember that reset-schema resets the development schema to production and deletes all development data.
• Remember that exporting a schema backs up schema text, not record data.
• Do not assume schema import to production is a normal deployment path merely because a local parser accepts an environment value. Apple's documented workflow imports into development and deploys schema to production through the supported CloudKit workflow.
• Run validate-schema before import-schema; use import-schema --validate only when one combined step is appropriate.
• Run delete-records with its default --dry-run true first. Use --dry-run false --yes only after reviewing the match count and filters.
• Prefer --fields-file or --fields-stdin over large inline JSON. This reduces quoting errors and accidental shell expansion.
• Do not use command-line --token in shared shells, process listings, CI logs, or recorded terminal sessions.
• Preserve pagination. If query-records returns continuationToken, continue until the requested scope is complete and stop on a repeated token.
• Expect indexed-query requirements. A queried or sorted field must have the appropriate CloudKit index; an unfiltered query may require ___recordID to be Queryable.

Use common schema recipes

Export a baseline

xcrun cktool export-schema \
  --team-id "$TEAM_ID" \
  --container-id "$CONTAINER_ID" \
  --environment development \
  --output-file Schema.ckdb

Keep .ckdb schema files in version control when the repository uses declarative CloudKit schema management. Review the diff before importing.

Validate, then import

xcrun cktool validate-schema \
  --team-id "$TEAM_ID" \
  --container-id "$CONTAINER_ID" \
  --environment development \
  --file Schema.ckdb

xcrun cktool import-schema \
  --team-id "$TEAM_ID" \
  --container-id "$CONTAINER_ID" \
  --environment development \
  --file Schema.ckdb

After import, export again and compare the effective schema when exact server state matters.

Reset test state

xcrun cktool reset-schema \
  --team-id "$TEAM_ID" \
  --container-id "$CONTAINER_ID"

Use this only when deleting all development data is intended. Reapply the tested schema and seed data in a deterministic order before integration tests.

Use common record recipes

Query with a bounded result

xcrun cktool query-records \
  --team-id "$TEAM_ID" \
  --container-id "$CONTAINER_ID" \
  --environment development \
  --database-type public \
  --zone-name _defaultZone \
  --record-type Book \
  --filters "pageCount >= int64Type:1000" \
  --requested-fields title pageCount \
  --limit 50

Read references/records-and-filters.md before composing field JSON, filters, sorts, assets, pagination, or deletions.

Create from a file

xcrun cktool create-record \
  --team-id "$TEAM_ID" \
  --container-id "$CONTAINER_ID" \
  --environment development \
  --database-type public \
  --zone-name _defaultZone \
  --record-type Book \
  --fields-file fixtures/book.json

Preview a bulk deletion

xcrun cktool delete-records \
  --container-id "$CONTAINER_ID" \
  --environment development \
  --database-type public \
  --zone-name _defaultZone \
  --record-type Book \
  --filters "fixtureRun == stringType:run-123" \
  --dry-run true

Do not change the dry run to false until the returned count and target are verified.

Diagnose failures

• If xcrun cannot find cktool, inspect xcode-select -p, verify Xcode 13 or newer is installed, and select the intended Xcode developer directory.
• If authentication fails, verify the operation uses the correct token class and check token expiration or revocation. User tokens are short-lived.
• If a query fails, inspect record type spelling, field types, zone, database, and Queryable/Sortable indexes.
• If JSON parsing fails, move inline fields to a file and validate the JSON separately.
• If the CLI reports usage error 64, re-read xcrun cktool help <subcommand> for the installed version.
• If CloudKit rejects a schema, run validate-schema, inspect the .ckdb diff, and verify the environment/container pair.

Load references on demand

• Read references/command-reference.md for the complete command surface, required flags, exit codes, and examples.
• Read references/records-and-filters.md for field JSON, assets, filters, sorts, indexes, pagination, and safe deletion.
• Read references/authentication-and-automation.md for token precedence, Keychain, environment variables, Xcode test setup, and CI patterns.
• Read references/sources.md for Apple documentation, WWDC sessions, samples, and the verification snapshot.