cktool(1) General Commands Manual cktool(1)

cktool - CloudKit Command Line Tool

cktool verb [token] [--option value] ...

save-token [token] [--type management | user] [--method file | keychain] [--force]

remove-token --type management | user [--method file | keychain] [--force]

export-schema [-t | --token token] --team-id team-id --container-id container-id --environment development | production --output-file output-file

import-schema [-t | --token token] --team-id team-id --container-id container-id --environment development | production [--validate] --file file

validate-schema [-t | --token token] --team-id team-id --container-id container-id --environment development | production --file file

reset-schema [-t | --token token] --team-id team-id --container-id container-id

create-record [-t | --token token] --team-id team-id --container-id container-id --environment development | production --database-type public | shared | private [--zone-name zone-name] --record-type record-type [--fields-file fields-file] [--fields-json fields-json] [--fields-stdin] [--asset-files asset-key-to-file-path ...]

query-records [-t | --token token] --team-id team-id --container-id container-id --environment development | production --database-type public | shared | private [--zone-name zone-name] [--record-type record-type] [--filters filters ...] [--sort-by sort-by ...] [--requested-fields requested-fields ...] [--limit limit] [--continuation-token continuation-token]

delete-record [-t | --token token] --container-id container-id --environment development | production --database-type public | shared | private [--zone-name zone-name] [--record-name record-name] [-y | --yes]

delete-records [-t | --token token] --container-id container-id --environment development | production --database-type public | shared | private [--zone-name zone-name] [--record-type record-type] [--filters filters ...] [--dry-run true | false] [-y | --yes]

get-teams [-t | --token token]

[-h | --help]

cktool is a CLI to assist with creating, validating, displaying and managing CloudKit database schemas and records stored in CloudKit containers. Most commands below require Internet connectivity.

There are several ways in which cktool can help during project development:

The tool must be authorized with a token each time it communicates with the CloudKit Console. One can easily create or remove tokens from local storage via the commands below. Tokens are saved to the login keychain by default, unless otherwise specified with the --method file | keychain option.

Note: While each command requiring authorization supports a --token argument, this is discouraged in multi-user environments to prevent the token from being exposed. Instead it is recommended to use save-token to persist tokens securely to the keychain, or by using the CLOUDKIT_MANAGEMENT_TOKEN and CLOUDKIT_USER_TOKEN environment variables.

To create tokens:

Saves a token to the specified store. If no other options are present, an interactive prompt follows to guide through the process.

Authorization token to save. If none is provided, a secure interactive prompt is used for input.

[--type management | user]
Type of token to save, optional. One of management or user. A management token is long-lived and is intended for container configuration only, like schema import and export. It cannot interact with data in the container. A user token is short-lived (several hours) and is used to perform database operations on behalf of the associated iCloud account. If this option is not provided, an interactive prompt follows.

[--method file | keychain]
The method to use when saving the token, optional. One of file or keychain, defaults to keychain. If file is specified, it is saved in ~/.config/cktool. For keychain, an entry is created in the login keychain under com.apple.icloud.cktool (cktoolmanagement_auth) for the management token, and com.apple.icloud.cktool (cktooluser_auth) for the user token.

[--force]
Forces overwrite of any existing token without prompting user confirmation.

To remove tokens:

Removes a previously saved authentication token if one exists.

Type of token to remove, mandatory. One of management or user.

[--method file | keychain]
The method to use when removing the token, optional. One of file or keychain, defaults to keychain. If file is specified, cktool tries to remove the token stored in ~/.config/cktool. For keychain, it will try to remove the entry created in the login keychain under the respective com.apple.icloud.cktool entry. It is an error to remove a nonexisting token.

[--force]
Forces removal of the existing token without prompting for user confirmation.

Commands under this category operate on the CloudKit Database schema inside a container that exists in a given environment. One can export, import, validate or reset the schema in that container.

To copy the schema from the CloudKit Database to the local machine:

Returns the current schema for a given container and environment.

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_MANAGEMENT_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

The Apple Developer Program team identifier. This option is mandatory.

The unique iCloud container identifier. This option is mandatory.

The container's environment, one of development or production. This option is mandatory.

[--output-file output-file]
An optional output path to write the schema file to. Prints to stdout if unspecified.

To import a schema into a CloudKit container:

Import the local schema file into the given CloudKit container and environment

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_MANAGEMENT_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

The Apple Developer Program team identifier. This option is mandatory.

The unique iCloud container identifier. This option is mandatory.

The container's environment, one of development or production. This option is mandatory.

[--validate]
Ensures the schema is valid with validate-schema before importing. Optional.

Path to the schema file to import. This option is mandatory.

To check with the CloudKit Console that a local schema is correct (before importing it):

Sends the contents of a local file containing a CloudKit database schema definition to the CloudKit Console for validation.

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_MANAGEMENT_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

The Apple Developer Program team identifier. This option is mandatory.

The unique iCloud container identifier. This option is mandatory.

The container's environment, one of development or production. This option is mandatory.

The path to a local file containing the schema definition to be validated. This option is mandatory.

To reset a development container's schema to the same schema used in the production container:

Resets the development environment schema of the container to match the production environment schema of the container and deletes all data in the development environment of the container.

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_MANAGEMENT_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

The Apple Developer Program team identifier. This option is mandatory.

The unique iCloud container identifier. This option is mandatory.

With these commands, one can create new records or query existing records.

To create a new record:

Creates a new record in a given database, returning the new record.

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_USER_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

The Apple Developer Program team identifier. This option is mandatory.

The unique iCloud container identifier. This option is mandatory.

The container's environment, one of development or production. This option is mandatory.

The database type (public, shared or private). This option is mandatory.

[--zone-name zone-name]
The record zone to create the record in. Optional, defaults to _defaultZone.

Record type being created. Must be defined in schema. This option is mandatory.

[--fields-file fields-file]
Path to a file containing JSON-formatted fields in {"KEY=": {"type": FIELD_TYPE, "value": VALUE}} format. Optional. Note that when FIELD_TYPE is assetType or assetListType, VALUE should refer to a key defined by --asset-files.

[--fields-json fields-json]
Inline JSON description of fields as an alternative to using a file. Optional.

[--fields-stdin]
Takes the description from standard input. Optional.

[--asset-files]
A map of asset keys to local file paths referenced by the provided JSON-formatted fields in KEY=/path/to/file format. Optional.

To query existing records from the CloudKit Database:

Queries the database for records with an optional set of filters.

If no filters are provided, all records will be returned, up to the limit specified.

If records matching the query exceed the limit, a continuationToken is returned at the top level of the JSON output, which can be used in subsequent query operations to get the next set of records.

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_USER_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

The Apple Developer Program team identifier. This option is mandatory.

The unique iCloud container identifier. This option is mandatory.

The database type (public, shared or private). This option is mandatory.

[--zone-name zone-name]
The record zone in which the records exist. Optional, defaults to _defaultZone.

The record type to be queried.

[--filters filters ...]
One or more optional filters described by strings to query with.

[--sort-by sort-by ...]
One or more optional sort descriptors.

[--requested-fields requested-fields ...]
One or more optional fields to request. If not specified, all fields are returned.

[--limit limit]
Optionally specify a maximum number of records returned in a single query, defaults to 200 records.

[--continuation-token continuation-token]
Continuation token used to request the next batch of result sets. It must be specified for querying and displaying subsequent results (e.g. greater than --limit).

To delete a single record:

Deletes a record from a given database by its unique record name.

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_USER_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

The unique iCloud container identifier. This option is mandatory.

The container's environment, one of development or production. This option is mandatory.

The database type (public, shared or private). This option is mandatory.

[--zone-name zone-name]
The record zone in which the record exists. Optional, defaults to _defaultZone.

The unique name of the record to delete. Usually a UUID.

[-y | --yes]
Confirms permanent deletion of any matching record, skipping interactive confirmation. Optional.

To delete multiple records:

Deletes records matching one or more filters from a given database. Performed as a dry-run operation by default, returning how many records match given filter set.

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_USER_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

The unique iCloud container identifier. This option is mandatory.

The container's environment, one of development or production. This option is mandatory.

The database type (public, shared or private). This option is mandatory.

[--zone-name zone-name]
The record zone in which the record exists. Optional, defaults to _defaultZone.

The record type to be queried.

[--filters filters ...]
One or more filters described by strings to match records with.

[--dry-run true | false]
Whether the operation should be a dry-run, only returning a count of how many records would be matched and deleted. Optional, defaults to true.

[-y | --yes]
Confirms permanent deletion of any matching records, skipping interactive confirmation. Optional.

[-h | --help]
Displays a list of options and typical usage. Does not constitute an error if invoked by itself, and exits with 0.

Returns a list of teams and their team identifier of which the developer account is a member of.

[-t | --token token]
The authorization token string, optional. If not present, it will be read from the CLOUDKIT_MANAGEMENT_TOKEN environment variable, the local store config file ~/.config/cktool or the login keychain, in that order.

$ cktool save-token abc123 --type management
Saves the management token "abc123" to the login keychain, under com.apple.icloud.cktool (cktoolmanagement_auth).

$ cktool save-token abc123 --type user
Saves the user token "abc123" to the login keychain, under com.apple.icloud.cktool (cktooluser_auth).

$ cktool import-schema --team-id WWDRTEAMID --container-id iCloud.com.mycompany.mycontainer --environment development --file /path/to/my/database/schema
Imports a schema from a local file into the given CloudKit container and environment. Reads the authorization token from the environment variable CLOUDKIT_MANAGEMENT_TOKEN, ~/.config/cktool or the login keychain (com.apple.icloud.cktool (cktoolmanagement_auth)), in that order.

$ cktool create-record --team-id WWDRTEAMID --container-id iCloud.com.mycompany.mycontainer --environment development --database-type private --fields-file /path/to/records/data
Creates a record in the authorized user's private database in the container using definitions from a file on the local filesystem. Reads the authorization token from the environment variable CLOUDKIT_USER_TOKEN, ~/.config/cktool or the login keychain (com.apple.icloud.cktool (cktooluser_auth)), in that order.

$ cktool create-record --team-id WWDRTEAMID --container-id iCloud.com.mycompany.mycontainer --environment development --database-type public --record-type Book --fields-json \

'{
"title": { "type": "stringType", "value": "The Mysterious Island" },
"pageCount": { "type": "int64Type", "value": 1464 },
"description": { "type": "stringType", "value": "An awesome book" },
"publishedOn": { "type": "timestampType", "value": "1875-09-12T21:12:42Z" },
"authorImage": { "type": "assetType", "value": "AUTHOR_IMG" },
"covers": { "type": "assetListType", "value": ["COVER_IMG_1", "COVER_IMG_2"] }
}' \
--asset-files AUTHOR_IMG=~/Pictures/jverne.jpg COVER_IMG_1=/tmp/LM1.jpg COVER_IMG_2=/tmp/LM2.jpg

Creates a record in the public database of the container's development environment iCloud.com.mycompany.mycontainer for a previously-defined Book schema record type from an inline definition in JSON format. Note that the asset fields use keys with file paths later defined by the --asset-files option. Reads the authorization token from the environment variable CLOUDKIT_USER_TOKEN, ~/.config/cktool or the login keychain (com.apple.icloud.cktool (cktooluser_auth)), in that order.

$ cktool delete-record --container-id iCloud.com.mycompany.mycontainer --environment development --database-type private --record-name UNIQUE-RECORD-ID
Deletes a record matching the unique record name provided from the authorized user's private database in the container. Reads the authorization token from the environment variable CLOUDKIT_USER_TOKEN, ~/.config/cktool or the login keychain (com.apple.icloud.cktool (cktooluser_auth)), in that order.

$ cktool delete-records --container-id iCloud.com.mycompany.mycontainer --environment development --database-type public --record-type Book --filters "pageCount >= 1400" --dry-run false
Deletes any Book records with a pageCount equal to or greater than 1400 from the public database in the container. Reads the authorization token from the environment variable CLOUDKIT_USER_TOKEN, ~/.config/cktool or the login keychain (com.apple.icloud.cktool (cktooluser_auth)), in that order.

The following environment variables affect the execution of cktool:

Contains the management authorization token in a SHELL environment variable. Takes precedence over the token being stored in a local file or the login keychain, but not if specified on the command line via --token.

Contains the user authorization token in a SHELL environment variable. Takes precedence over the token being stored in a local file or the login keychain but not if specified on the command line via --token.

~/.config/cktool
File-backed storage for locally stored tokens.

An exit code of 0 (EX_OK) is returned on all invocation that were completed successfully.

An exit code of 1 is returned for errors in operation.

An exit code of 64 (EX_USAGE) is returned for all incorrect invocations. Invoking with --help is not an error.

security(1)

Copyright (C) 2021, Apple, Inc.

7 June 2021 Apple CloudKit Command Line Tool