Command-Line Tools

What are Command-Line Tools?

PatchKit Command-Line Tools (pkt) allow you to manage your applications from a command-line interface. The tools enable you to:

Query information about your applications and versions
Create new applications and versions
Upload new version files
Monitor the progress of new version processing
Publish new versions

Using the tools provides two key benefits:

Automation — for example, in the context of continuous integration or delivery.
Faster uploads — you can upload locally computed binary differences instead of all application files, using the --mode diff option.

Not all PatchKit plans include API access, which is required for the Command-Line Tools to work. To check if your account has API access, please visit your Account page.

Installation

Download pkt (Latest Release)

To install the PatchKit Command-Line Tools, follow these steps:

Download the latest pkt binary for your operating system from GitHub. Available binaries:
- Windows: pkt-windows-amd64.exe
- macOS (Apple Silicon): pkt-darwin-arm64
- macOS (Intel): pkt-darwin-amd64
- Linux: pkt-linux-amd64 or pkt-linux-arm64
Rename the downloaded file to pkt (or pkt.exe on Windows) and place it in a directory of your choice. We recommend C:\patchkit_tools on Windows and /usr/local/bin on macOS and Linux.
On macOS and Linux, make the file executable: chmod +x /path/to/pkt
On macOS, remove the quarantine attribute: sudo xattr -d com.apple.quarantine /path/to/pkt

Replace /path/to/pkt with the actual location where you placed the binary (e.g., /usr/local/bin/pkt).

For more convenient usage, add the installation directory to your PATH environment variable. If you placed pkt in /usr/local/bin on macOS or Linux, it is likely already on your PATH. For Windows, find instructions here.

Verify the installation by running:

pkt --version

You should see output like pkt version 1.1.1.

Upgrading

To upgrade to a newer version, download the latest binary from GitHub and replace the existing pkt file.

Getting Started

To effectively use PatchKit, it’s important to have a basic understanding of the command line, whether it be Windows’ Command Prompt, macOS Terminal, or Linux Terminal. Here are some resources to help you get started:

To use PatchKit’s tools, enter the following in the command line:

pkt [command] [flags]

To view a list of all available commands, run:

pkt --help

For specific information on a particular command, such as version push, use:

pkt version push --help

Before using the tools, you’ll need two pieces of information:

API key — your unique key for accessing PatchKit services. Find it on your Account page.
Application secret — the secret code for the specific application you want to manage. Find it on your application’s overview page in the PatchKit Panel.

You can pass these with the --api-key and --app flags, or set the PATCHKIT_API_KEY and PATCHKIT_APP environment variables.

Deploying an Application

To deploy an application with PatchKit, use the version push command. This command creates a new version, uploads the files, waits for server processing, and optionally publishes it.

Interactive Mode

pkt version push --interactive

The interactive mode will prompt you for all required information (API key, application secret, version label, and path to files).

Scripted Mode

You can provide all information as command-line arguments:

pkt version push \
  --api-key <API_KEY> \
  --app <APP_SECRET> \
  --label "1.0" \
  --files /path/to/my_game \
  --publish \
  --wait

Replace <API_KEY>, <APP_SECRET>, and /path/to/my_game with your actual values.

On success, you should see output like:

Acquiring lock...
Creating draft version...
Mode: diff (auto-detected)
Downloading signatures from v4...
Computing diff...
Diff: 2 added, 3 modified, 0 removed, 10 unchanged
Packing diff...
Uploading diff (24 MB)...
Processing...
Publishing...
Version v5 pushed successfully (mode: diff). Version is published.

Please ensure that the directory you specify only contains the files you want to upload. The tool will automatically upload all files in the directory.

Key Flags

Flag	Description
`--publish` / `-p`	Publish the version automatically after processing completes
`--wait` / `-w`	Wait for publishing to finish (implies `--publish`)
`--overwrite-draft`	Replace an existing draft version instead of failing
`--changelog` / `-c`	Set changelog text, or use `@path/to/file` to read from a file
`--mode` / `-m`	Upload mode: `auto` (default), `content`, `diff`, `diff-encrypted`, `diff-fast`
`--skip-processing`	Upload without waiting for server processing
`--dry-run`	Show what would happen without making any changes

Environment Variables

Instead of passing flags every time, you can set environment variables:

export PATCHKIT_API_KEY=<your_api_key>
export PATCHKIT_APP=<your_app_secret>
pkt version push --files /path/to/my_game --label "1.0" --publish --wait

Configuration File

For projects that use PatchKit regularly, you can create a .patchkit.yml file in your project directory:

api_key: your_api_key
app: your_app_secret

The tool also reads a user-level config from ~/.config/patchkit/config.yml. Run pkt config show to see all active configuration values and their sources.

Working with Channels

Channels allow you to publish different variants of your application — such as stable, beta, or testing — from a single set of uploaded files. A group holds the actual content, and channels link to specific group versions. For more details on channels, see the Channels section.

Upload and Publish a Group Version: Use version push to upload and publish a group version. Provide your group secret as the application secret, which you can find on your group’s overview page in the PatchKit Panel.
```
 pkt version push \
   --api-key <API_KEY> \
   --app <GROUP_SECRET> \
   --label "1.0" \
   --files /path/to/files \
   --publish --wait
```
Note the version ID from the output (e.g., v5) — you’ll need it for the next step.
Link Group Version to a Channel: Use channel push to link the group version to a channel. Provide your channel secret as the application secret.
```
 pkt channel push \
   --api-key <API_KEY> \
   --app <CHANNEL_SECRET> \
   --label "1.0" \
   --group-version <GROUP_VERSION_ID> \
   --publish --wait
```
Replace <GROUP_VERSION_ID> with the numeric version ID from the previous step (e.g., 5).

You can automate linking the latest group version to a channel in your continuous integration system using the --latest flag. This will find and link the most recent published group version to the channel.

pkt channel push \
  --api-key <API_KEY> \
  --app <CHANNEL_SECRET> \
  --label "1.0" \
  --latest \
  --publish --wait

Troubleshooting

Here are some common issues you may encounter:

Error	Cause	Solution
`draft version already exists`	A previous draft was not published or removed	Add `--overwrite-draft` to your command
`401 Unauthorized` or `403 Forbidden`	Invalid or missing API key	Check your API key on the Account page
`no previous published version found for diff mode`	First version cannot use diff mode	The tool auto-detects this — if using `--mode diff`, switch to `--mode content`
`context deadline exceeded`	Network timeout during upload	The tool retries automatically (5 attempts). Check your network connection
`cannot upload directly to a channel app`	Trying to push content to a channel instead of a group	Use `pkt channel push` to link a group version, or use `pkt version push` with the group secret

For server-side processing errors, check the version status in the PatchKit Panel.

Other Commands

The version push and channel push commands cover the most common workflows. For additional operations, use pkt --help to see all available commands, including:

pkt version list — list all versions for an application
pkt version status — check version processing and publish status
pkt app list — list your applications
pkt app info — show application details
pkt config show — display active configuration

Use pkt [command] --help for full details on any command.

Next Steps

Applications — learn about managing applications, groups, and channels in the PatchKit Panel
API Reference — use the REST API directly for advanced integrations
Source Code — pkt is open source on GitHub