⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
apple-cktool
Operates Apple's Xcode-bundled `cktool` command-line utility for CloudKit development automation on macOS. Use when Codex needs to run, script, explain, or troubleshoot `xcrun cktool`; manage `.ckdb` schemas with export, validate, import, or reset; discover CloudKit teams; create, query, or delete test records; configure management or user tokens in Keychain or CI; or prepare CloudKit-backed integration tests. For equivalent typed JavaScript or TypeScript automation, use `apple-cktool-js` with t
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Agent Skills
A collection of skills for AI agents.
Overview
This repository contains reusable skills that enhance AI agent capabilities. Skills are modular, composable units that provide specialized knowledge and workflows for agents.
Install a Skill
The open-source skills CLI runs directly through npx, so it does not require a separate global installation.
Browse the skills in this repository:
npx skills add bastos/skills --list
Install interactively and choose a skill and detected agent:
npx skills add bastos/skills
To install a specific skill, pass its name from the table below. For example:
npx skills add bastos/skills --skill unhobble-agent-context
Installations are project-scoped by default. Add --global to make the skill available across projects and --agent to target a particular agent:
npx skills add bastos/skills --skill unhobble-agent-context --global --agent codex
Use --yes for a non-interactive installation. Verify global skills for an agent with:
npx skills list --global --agent codex
Review a skill's SKILL.md, scripts, and references before installing it because skills run with the agent's permissions. See the CLI documentation for supported sources, agents, and management commands.
Skills
| Skill | Description |
|---|---|
| apple-cktool | Automate CloudKit schema and test-data workflows with Apple's Xcode-bundled cktool CLI on macOS, including safe authentication, validation, reset, query, and deletion procedures. |
| apple-cktool-js | Build typed CloudKit automation for Node.js, browsers, and CI with Apple's CKTool JS packages, Promise APIs, secure token injection, and guarded schema and record operations. |
| audit-training-experiment | Audit ML experiments for reproducibility, evidence integrity, leakage, checkpoint identity, evaluation validity, and overclaimed conclusions. |
| awk | Expert GNU awk (gawk) one-liner generation and transformation for text field processing, column extraction, aggregation, CSV/TSV reformatting, and log analysis. |
| close-out-ml-experiment | Preserve experiment evidence, reconcile report discrepancies, record the canonical decision and limitations, and prepare a concise handoff. |
| compare-models-blindly | Create seeded blinded model-comparison packets and evaluate candidate outputs with reversed order to control identity and presentation bias. |
| conventional-commits | Format commit messages using the Conventional Commits specification for automated tooling, changelog generation, and semantic versioning. |
| design-resumable-model-evaluation | Design strict model benchmarks that persist per-case evidence, resume without repeating work, and use mathematically valid early stopping. |
| ios-design-review | Review iOS app UI/UX design quality using Apple's design principles and the Liquid Glass-era design language from WWDC25/26. |
| mikrotik-routeros | Configure and automate MikroTik RouterOS routers through the terminal, CLI, .rsc imports, scripts, Scheduler, Netwatch, firewall, NAT, DHCP, bridge, VLAN, routing, and backups. |
| obsidian-daily | Manage Obsidian Daily Notes via the official Obsidian CLI. Create, open, and append entries to daily notes, read past notes by date, and search vault content. |
| orbstack-cli | Drive OrbStack from the terminal on macOS: the orb/orbctl CLI for Linux VMs, Docker engine usage, .orb.local domains and networking, SSH, Kubernetes, config keys, and headless/CI automation. |
| package-private-ml-artifacts | Inventory, hash, scan, and verify ML artifacts before an explicitly approved private upload. |
| prepare-training-corpus | Build deterministic train, validation, and test corpora with provenance, group-safe splits, manifests, hashes, and leakage checks. |
| proxmox-admin | Administer Proxmox VE hosts, create and manage KVM virtual machines with qm, manage LXC containers with pct, and configure storage, networking, and clusters via the CLI. |
| review-ios-ui-apple-hig | Review iOS app UI against Apple Human Interface Guidelines and iOS platform conventions using page-specific Apple reference notes. |
| review-training-data-quality | Audit training corpora for distribution collapse, ambiguity, context sufficiency, hard negatives, abstention behavior, leakage, and label defensibility. |
| run-hugging-face-training-smoke | Run a bounded private Hugging Face training smoke with immutable inputs, preflight checks, stop gates, checkpoint verification, and reproducible evidence. |
| sed | Expert GNU sed one-liner generation for stream editing, in-place file editing, bulk find/replace, log filtering, and text transformation pipelines. |
| select-and-verify-best-checkpoint | Verify evaluation cadence, best-checkpoint selection, and held-out inference checkpoint identity before trusting test metrics. |
| send-to-minion | Delegate a prompt to exactly one helper agent, supervise it to completion, verify its result, and return the parent agent's final answer. |
| swift-review | Review Swift/Xcode codebases, pull requests, local changes, or individual files against Swift best practices for style, API design, memory management, performance, and testing. |
| tmuxinator | Create, edit, and debug tmuxinator project configurations for complex tmux session layouts and automated development environment startup. |
| topydo | Manage todo.txt tasks using topydo CLI. Add, list, complete, prioritize, tag, and organize tasks with dependencies, due dates, and recurrence. |
| unhobble-agent-context | Audit and redesign agent context across system prompts, repository guidance, skills, tools, memory, and references while preserving authority and safety boundaries. |
| validate-structured-model-output | Validate JSON or tool-call model outputs without repair across parsing, schema, identifiers, semantics, replay, and safety gates. |
| write-a-prompt | Create a copy-ready prompt from a rough request, source material, or the current conversation without performing the underlying task. |
Learn More
Visit agentskills.io for documentation and examples.
License
MIT
// HOW IT'S BUILT
// FILES
7 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
apple-cktool/SKILL.md8.0 KB1ce96b6b5bebupstream ↗
--- name: apple-cktool description: Operates Apple's Xcode-bundled `cktool` command-line utility for CloudKit development automation on macOS. Use when Codex needs to run, script, explain, or troubleshoot `xcrun cktool`; manage `.ckdb` schemas with export, validate, import, or reset; discover CloudKit teams; create, query, or delete test records; configure management or user tokens in Keychain or CI; or prepare CloudKit-backed integration tests. For equivalent typed JavaScript or TypeScript automation, use `apple-cktool-js` with this skill. --- # 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 | Need | Use | |---|---| | Shell commands, Xcode schemes, or a macOS runner | This skill | | TypeScript, Node.js, browser tooling, or non-macOS CI | `apple-cktool-js` | | A shell wrapper around a few stable commands | This skill | | Reusable branching logic, typed models, updates, or richer error handling | `apple-cktool-js` | 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: ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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.apple-cktool/references/authentication-and-automation.md4.2 KBce14437b8ffaupstream ↗
# Authentication and automation ## Token roles | Token | Scope and purpose | Typical commands | |---|---|---| | Management | Long-lived; tied to the developer/team context; no record-data access | `get-teams`, schema export/validate/import/reset | | User | Short-lived; represents an iCloud user; accesses public/private/shared records as that user | create/query/delete records | Generate tokens in CloudKit Console. A token may only be shown once, may expire, and may be revoked. Do not store either token in source control. ## Credential lookup and precedence The local man page documents this effective order: 1. Explicit `--token` 2. Environment variable 3. File store at `~/.config/cktool` 4. Login Keychain Schema commands read `CLOUDKIT_MANAGEMENT_TOKEN`. Record commands read `CLOUDKIT_USER_TOKEN`. Avoid the explicit command-line token because it can appear in shell history, process inspection, terminal recordings, and CI logs. ## Local development Prefer the secure interactive flow, which avoids placing the token in the command: ```bash xcrun cktool save-token --type management xcrun cktool save-token --type user ``` Keychain is the default. Use file storage only when its weaker plaintext/file-access properties are understood: ```bash xcrun cktool save-token --type management --method file ``` Remove obsolete credentials from the same store: ```bash xcrun cktool remove-token --type management xcrun cktool remove-token --type user ``` ## CI and secret managers Inject tokens only for the process that needs them. Prefer a 1Password Developer Environment, a local environment mount, or the CI provider's encrypted secret mechanism. Do not create a committed `.env` file. Example shape: ```bash CLOUDKIT_MANAGEMENT_TOKEN="$INJECTED_MANAGEMENT_TOKEN" \ xcrun cktool validate-schema \ --team-id "$TEAM_ID" \ --container-id "$CONTAINER_ID" \ --environment development \ --file Schema.ckdb ``` Do not enable shell tracing (`set -x`) around secret injection. Redact environment dumps and command diagnostics. Use a user token cautiously in CI: Apple documents user tokens as short-lived and interactively generated, which limits unattended data workflows. Design tests to fail clearly when reauthentication is required. ## Xcode integration-test setup A deterministic development test pipeline commonly performs: 1. Select the expected Xcode and verify `cktool`. 2. Reset the development schema to production when a clean baseline is truly required. 3. Validate the repository's `.ckdb` file. 4. Import the schema into development. 5. Seed uniquely identifiable test records. 6. Run integration tests. 7. Delete only records labeled for that test run, or reset the isolated development container when authorized. Prefer a dedicated development container or test namespace. Parallel jobs can race when they reset or seed the same container. When adding a Run Script build phase or scheme pre-action: - Resolve paths from stable project variables rather than the caller's current directory. - Quote every path and identifier. - Make a `cktool` failure stop the test run. - Never echo tokens. - Avoid resetting a shared container on every developer build. ## Production controls - Keep production writes out of default CI branches and pull-request jobs. - Require environment protection and explicit approval for a production record mutation. - Log target identifiers and operation metadata, never credentials or private record contents. - Prefer read-only verification and bounded queries. - Treat schema deployment to production as a separate release action from development schema import. ## Authentication troubleshooting - Management operation rejected: verify a management token is injected and the account belongs to the target team. - Record operation rejected: verify a current user token and access to the selected container/database/zone. - Works locally but not in CI: confirm the CI shell receives the environment variable and tracing does not redact it into an empty value. - Wrong account behavior: remove stale tokens from the selected store and save the intended token again. - Intermittent user-token failures: expect expiration and create a clear reauthentication path instead of retrying indefinitely.apple-cktool/references/command-reference.md6.3 KB0120db43b5c7upstream ↗
# cktool command reference Use the installed tool's help as the source of truth: ```bash xcrun cktool --help xcrun cktool help <subcommand> man cktool ``` This reference reflects `cktool 1.0.23001`, observed with Xcode on 2026-07-21. Recheck flags before generating automation for another Xcode version. ## Contents - [Global behavior](#global-behavior) - [Token storage](#token-storage) - [Schema commands](#schema-commands) - [Record commands](#record-commands) - [Team discovery](#team-discovery) - [Exit status](#exit-status) ## Global behavior Invoke the tool through `xcrun` so the active Xcode toolchain selects the binary: ```bash xcrun cktool <subcommand> [options] ``` The command is stateless from the CloudKit server's perspective: each operation becomes a request to the CloudKit API. Local state is limited to optional credential storage. | Command | Authorization | Mutates remote state | |---|---|---| | `save-token` / `remove-token` | None | No; changes local credential storage | | `get-teams` | Management | No | | `export-schema` | Management | No | | `validate-schema` | Management | No | | `import-schema` | Management | Yes | | `reset-schema` | Management | Yes; deletes development data | | `query-records` | User | No | | `create-record` | User | Yes | | `delete-record` / `delete-records` | User | Yes | ## Token storage ### `save-token` ```text cktool save-token [<token>] [--type <management|user>] [--method <file|keychain>] [--force] ``` - Omit `<token>` to enter it through the secure interactive prompt. - Default storage is the login Keychain. - File storage uses `~/.config/cktool`. - Use `--force` only when intentionally replacing an existing token. Preferred local setup: ```bash xcrun cktool save-token --type management xcrun cktool save-token --type user ``` ### `remove-token` ```text cktool remove-token --type <management|user> [--method <file|keychain>] [--force] ``` Match `--method` to the store used by `save-token`. ## Schema commands ### `export-schema` ```text cktool export-schema [--token <token>] --team-id <team-id> --container-id <container-id> --environment <development|production> [--output-file <path>] ``` Without `--output-file`, the schema is written to standard output. Prefer an explicit file when the output will be diffed or committed. ```bash xcrun cktool export-schema \ --team-id WWDRTEAMID \ --container-id iCloud.com.example.MyApp \ --environment development \ --output-file CloudKitSchema.ckdb ``` ### `validate-schema` ```text cktool validate-schema [--token <token>] --team-id <team-id> --container-id <container-id> --environment <development|production> --file <path> ``` Validation checks schema syntax and whether the schema can be imported into the target container/environment. It does not mutate the schema. ### `import-schema` ```text cktool import-schema [--token <token>] --team-id <team-id> --container-id <container-id> --environment <development|production> [--validate] --file <path> ``` Apple's documented automation flow imports into development. Prefer a separate `validate-schema` call when logs should clearly distinguish validation from mutation. ```bash xcrun cktool import-schema \ --team-id WWDRTEAMID \ --container-id iCloud.com.example.MyApp \ --environment development \ --validate \ --file CloudKitSchema.ckdb ``` ### `reset-schema` ```text cktool reset-schema [--token <token>] --team-id <team-id> --container-id <container-id> ``` This command always targets the development environment, resets its schema to match production, and deletes all data in development. If no schema exists in production, the resulting development schema may be empty. ## Record commands Record commands require a user token. Database type values are `public`, `private`, or `shared`. Zone defaults to `_defaultZone` where the command permits omission. ### `create-record` ```text cktool create-record [--token <token>] --team-id <team-id> --container-id <container-id> --environment <development|production> --database-type <public|private|shared> [--zone-name <zone>] --record-type <record-type> [--fields-file <path>] [--fields-json <json>] [--fields-stdin] [--asset-files <KEY=path> ...] ``` Use exactly one convenient field-input route. Asset values in the JSON refer to keys supplied by `--asset-files`. ### `query-records` ```text cktool query-records [--token <token>] --team-id <team-id> --container-id <container-id> --environment <development|production> --database-type <public|private|shared> [--zone-name <zone>] --record-type <record-type> [--filters <filter> ...] [--sort-by <sort> ...] [--requested-fields <field> ...] [--limit <1...>] [--continuation-token <token>] ``` The default page limit is 200. When more records match, read the top-level `continuationToken` and pass it to the next query with the same target, filters, and sort order. ### `delete-record` ```text cktool delete-record [--token <token>] --container-id <container-id> --environment <development|production> --database-type <public|private|shared> [--zone-name <zone>] --record-name <record-name> [--yes] ``` The installed command does not accept `--team-id`. Query the record first and preserve the interactive confirmation unless noninteractive deletion is explicitly intended. ### `delete-records` ```text cktool delete-records [--token <token>] --container-id <container-id> --environment <development|production> --database-type <public|private|shared> [--zone-name <zone>] --record-type <record-type> [--filters <filter> ...] [--dry-run <true|false>] [--yes] ``` The default is `--dry-run true`, which returns how many records match. Always run the preview first. Repeat filters exactly when changing to `--dry-run false`. ## Team discovery ### `get-teams` ```text cktool get-teams [--token <token>] ``` This returns the teams available to the management-token owner. Parse the returned identifier rather than matching only on a display name when scripting. ## Exit status | Code | Meaning | |---|---| | `0` | Operation completed successfully | | `1` | Operational error | | `64` | Incorrect invocation / usage error | Invoking help is successful and exits with `0`. Do not treat a zero exit code as proof that the intended remote state is correct; verify by export or query after mutations.apple-cktool/references/records-and-filters.md5.7 KBb72fa35e9e21upstream ↗
# Records, field JSON, filters, and deletion Read this reference before generating record fixtures, queries, sorts, pagination loops, or deletion commands. ## Contents - [Target model](#target-model) - [Field JSON](#field-json) - [Assets](#assets) - [Filters](#filters) - [Sorts and indexes](#sorts-and-indexes) - [Pagination](#pagination) - [Safe deletion](#safe-deletion) ## Target model A record operation must resolve: - `container-id`, such as `iCloud.com.example.MyApp` - `environment`: `development` or `production` - `database-type`: `public`, `private`, or `shared` - `zone-name`, defaulting to `_defaultZone` - `record-type` for creation, query, or bulk deletion - `record-name` for single deletion Private and shared data access is performed on behalf of the user represented by the user token. Do not assume the token has access to another user's data. ## Field JSON Supply fields as a JSON object whose keys are field names and whose values contain a CloudKit field type and value: ```json { "title": { "type": "stringType", "value": "The Mysterious Island" }, "pageCount": { "type": "int64Type", "value": 1464 }, "rating": { "type": "doubleType", "value": 4.8 }, "publishedOn": { "type": "timestampType", "value": "1875-09-12T21:12:42Z" }, "fixtureRun": { "type": "stringType", "value": "run-123" }, "tags": { "type": "stringListType", "value": ["fixture", "classic"] } } ``` Prefer a checked-in fixture file and `--fields-file` for repeatable test data: ```bash jq empty fixtures/book.json xcrun cktool create-record \ --team-id "$TEAM_ID" \ --container-id "$CONTAINER_ID" \ --environment development \ --database-type public \ --record-type Book \ --fields-file fixtures/book.json ``` Avoid interpolating untrusted text into `--fields-json`. Build JSON with a real encoder such as `jq` and pass it through standard input or a file. ## Assets Represent an asset field with an asset key, then map that key to a local path: ```json { "authorImage": { "type": "assetType", "value": "AUTHOR_IMAGE" }, "covers": { "type": "assetListType", "value": ["COVER_FRONT", "COVER_BACK"] } } ``` ```bash xcrun cktool create-record \ --team-id "$TEAM_ID" \ --container-id "$CONTAINER_ID" \ --environment development \ --database-type public \ --record-type Book \ --fields-file fixtures/book-with-assets.json \ --asset-files \ AUTHOR_IMAGE=fixtures/author.jpg \ COVER_FRONT=fixtures/front.jpg \ COVER_BACK=fixtures/back.jpg ``` Verify every asset path exists and is suitable for upload before executing. ## Filters Write each filter as one shell argument: ```text FIELD_NAME OPERATOR VALUE ``` Example: ```bash --filters "pageCount >= 1000" "title == stringType:The Mysterious Island" ``` Common operators supported by the CLI include: - `==` / `EQUALS` - `!=` / `NOT_EQUALS` - `<` / `LESS_THAN` - `<=` / `LESS_THAN_OR_EQUALS` - `>` / `GREATER_THAN` - `>=` / `GREATER_THAN_OR_EQUALS` - `NEAR` - `CONTAINS_ALL_TOKENS` - `CONTAINS_ANY_TOKENS` - `LIST_CONTAINS_ANY` - `LIST_NOT_CONTAINS_ANY` The CLI attempts to infer bare values. Examples from Apple's sample parser include numbers, timestamps, and locations. Make ambiguous values explicit: ```text stringType:2021-01-01 int64Type:123 doubleType:6.123 ``` Quote the complete filter so the shell does not interpret `<`, `>`, spaces, or wildcard-like characters. Verify the exact accepted field types with the installed man page when using references, locations, lists, or timestamps. ## Sorts and indexes Pass each sort descriptor as its own argument and inspect `man cktool` for the installed syntax. Keep sorting deterministic when paginating, ideally with a stable tie-breaker. CloudKit queries depend on schema indexes: - Fields used in filters need a Queryable index. - Fields used in sorting need a Sortable index. - An unfiltered query may require `___recordID` to be Queryable. Do not work around a missing index by broad-fetching production data. Update and deploy the schema intentionally. ## Pagination `query-records` returns at most the selected limit, defaulting to 200. When the JSON response contains a top-level `continuationToken`: 1. Preserve the exact container, environment, database, zone, record type, filters, requested fields, and sorts. 2. Add `--continuation-token <value>` to the next call. 3. Continue until no continuation token is returned or the user's requested bound is reached. 4. Track seen tokens and stop with an error if CloudKit returns the same continuation token twice. 5. Never print a continuation token unnecessarily in public logs; treat it as transient request state. Use `jq` to extract fields without losing errors: ```bash response=$(xcrun cktool query-records ...) printf '%s\n' "$response" | jq -e '.records // .result.records' continuation=$(printf '%s\n' "$response" | jq -r '.continuationToken // empty') ``` Adapt the JSON path to the installed tool's actual response. Do not suppress a nonzero `cktool` exit status inside a pipeline. ## Safe deletion ### Single record 1. Query or otherwise resolve the exact `recordName`. 2. Confirm container, environment, database, and zone. 3. Run `delete-record` without `--yes` for interactive local work. 4. Re-query to confirm absence. ### Multiple records 1. Require one or more narrow filters even if the parser permits omission. 2. Run with `--dry-run true`. 3. Record the returned match count. 4. Re-read the exact command and filters. 5. Run with `--dry-run false`; add `--yes` only in an authorized noninteractive flow. 6. Re-run the dry run to confirm zero remaining matches when that is the intended state. Never bulk-delete production records as a cleanup convenience. Establish an explicit recovery or backup story first.apple-cktool/references/sources.md1.9 KB31cbf5f9cc7aupstream ↗
# Official sources and verification notes Use these sources to refresh behavior when Xcode, CloudKit Console, or the API changes. ## Apple documentation - [Using cktool](https://developer.apple.com/icloud/ck-tool/) - [Automating CloudKit Development](https://developer.apple.com/icloud/cloudkit/automating/) - [CloudKit](https://developer.apple.com/icloud/cloudkit/) - [Integrating a Text-Based Schema into Your Workflow](https://developer.apple.com/documentation/cloudkit/integrating_a_text-based_schema_into_your_workflow) ## Apple sessions - [Automate CloudKit tests with cktool and declarative schema — WWDC21 10118](https://developer.apple.com/videos/play/wwdc2021/10118/) - [Meet CloudKit Console — WWDC21 10117](https://developer.apple.com/videos/play/wwdc2021/10117/) - [Meet CKTool JS — WWDC22 10116](https://developer.apple.com/videos/play/wwdc2022/10116/) ## Apple samples - [CloudKit tooling sample repository](https://github.com/apple/sample-cloudkit-tooling) - [cktool CLI samples](https://github.com/apple/sample-cloudkit-tooling/tree/main/cktool-cli) - [Schema-management sample](https://github.com/apple/sample-cloudkit-tooling/tree/main/cktool-cli/schema-management) - [Record-operation sample](https://github.com/apple/sample-cloudkit-tooling/tree/main/cktool-cli/record-operations) - [Filter syntax sample](https://github.com/apple/sample-cloudkit-tooling/blob/main/cktool-cli/Arguments/Filters.md) ## Local verification snapshot Verified on 2026-07-21: - `xcrun --find cktool` resolved inside `/Applications/Xcode.app`. - `xcrun cktool --version` returned `1.0.23001`. - The installed command surface contained token save/remove, schema export/import/validate/reset, record create/query/delete, and team discovery. Refresh with: ```bash xcrun --find cktool xcrun cktool --version xcrun cktool --help xcrun cktool help <subcommand> man cktool ``` Treat this snapshot as evidence about the inspected Xcode, not a permanent version guarantee.apple-cktool/agents/openai.yaml228 B7f6ba852eaf8upstream ↗
interface: display_name: "Apple cktool" short_description: "Automate CloudKit with Apple’s macOS CLI" default_prompt: "Use $apple-cktool to plan and execute a safe CloudKit schema or record workflow with the Xcode CLI."README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/bastos-skills-apple-cktool.md