CodeKit ships with a command-line tool named, appropriately, codekit. It can do almost anything the app can do: compile files, build projects, change settings, install npm packages, open the Preview Server, add and remove projects, manage sidebar groups, skip folders, and much more. Everything it does happens inside the running CodeKit app, so what you see in the window and what the command line reports are always the same thing.
Built For AI Agents
The CLI exists mainly so that AI agents such as Claude Code, Codex, and Grok can drive CodeKit for you. Choose Tasks > Install Agent Skills in CodeKit's menu bar. CodeKit installs a short markdown file that teaches agents how to use the CLI. You never have to explain the app or paste documentation. (A public copy of that file is at codekitapp.com/agent-skill.txt, and this whole help site is available as one Markdown file at codekitapp.com/llms-full.txt.) Just tell your agent, "Create a new website for XYZ in this folder. Use CodeKit."
NOTE: The CLI controls the CodeKit app; it is not a standalone compiler. If CodeKit isn't running when a command arrives, the CLI launches it, unless you pass --no-launch, in which case the command exits with code 3.
Humans Are Welcome, Too
You don't need an AI agent to use the CLI. It works great in shell scripts, git hooks, Keyboard Maestro macros, launchd jobs, or anything else that can run a command. Here are a few examples:
Compile A File
codekit process src/styles/app.scss
Compiles a file exactly as if you had just saved it, including any files that import it. The reply lists what was actually compiled and any problems that were found.
Build A Project
codekit build ~/clients/someProject --clean
Builds an entire project. The --clean flag empties the Build Folder first, for that build only; the project's own "clean build" setting is left alone. Building is rarer than you'd think: CodeKit compiles files one at a time as they're saved, so build only when many files are out of date or the Build Folder has to be made from scratch.
Open The Preview Server
codekit preview --browser com.apple.Safari
Opens the Preview Server in a specific browser. Leave off --browser to use the one you've chosen in CodeKit.
Get Script-Friendly Output
codekit status --json
Every command accepts --json, which makes the reply easy to parse in a script. It's the default whenever the output isn't a terminal. Exit codes are meaningful, too; the full list is below.
Every Command
All commands take an optional project path. If you omit that, the project is the current directory. Arguments in angle brackets are required and those in square brackets are optional.
Inspect
codekit status What CodeKit is doing, and the current log cursor codekit projects Every project and framework codekit schema The whole API, with notes codekit log [--since <cursor>] Read the log from a cursor codekit wait Wait until nothing is happening
Compile, Build, Preview
codekit process <path>... Compile files, as though they had just been saved codekit build [<path>] [--clean] Build a whole project codekit optimize <image>... Optimize images in place codekit check <file>... Check syntax (JavaScript only) codekit packages <action> [<pkg>...] npm: install, forceInstall, uninstall, update, prune codekit preview Open the preview address in a browser codekit refresh [<path>] [--all] Re-read projects from disk
Projects
codekit add <path> [--framework] Add a folder as a project (or framework) codekit remove <path> Remove a project codekit enable <path> Switch a project on (and refresh it) codekit disable <path> Switch a project off; CodeKit stops watching it codekit watch pause | resume Stop or resume watching every project codekit rename <path> --name <to> Change what CodeKit calls a project, not the folder
Sidebar Groups
codekit groups Every sidebar group, and what is in each codekit groups add <name> Make a group codekit groups remove <name> Delete it; its projects go back to Projects codekit groups rename <name> <to> Rename it codekit move <path> --group <name> Move a project into a group (omit --group for Projects)
Settings, Defaults, Files
codekit settings [<path>] Every setting a project holds codekit settings set <key>=<value>... Change settings (all or nothing) codekit settings schema What settings exist and what each one does codekit settings apply-output-paths Recalculate output paths for existing files codekit defaults The settings a new project starts with codekit defaults set <key>=<value>... Change them (affects new projects only) codekit defaults schema Which of those settings exist codekit files [<path>] Every file CodeKit is watching in a project codekit files settings <file> One file's own settings codekit files set <file> <key>=<value>... Change one file (all or nothing) codekit files schema <file> What settings that file has codekit files skip <folder>... Stop indexing these folders codekit files unskip <folder>... Index them again
Hooks, Build Steps, WebP Presets, Custom Extensions
codekit collections [<path>] Hooks, build steps, WebP presets, custom extensions codekit collections add --kind <name> Make a row (a build step also needs --type) codekit collections remove --kind <name> Delete a row, by --id codekit collections move --kind buildSteps Move a build step to --position codekit collections set --kind <name> Change a row, by --id (all or nothing) codekit collections schema What a row of each kind holds
Options
--json Print the reply as JSON (the default when output is not a terminal) --no-wait Return as soon as the work is submitted --timeout <seconds> How long to wait (default 600) --settle <milliseconds> Pause before deciding nothing is happening (default 400) --since <cursor> Report only what happened after this log cursor --project <path> Restrict to one project --errors-only Only errors --exactly With process: compile precisely this file (rarely right) --socket <path> Talk to a socket other than the usual one --no-launch Do not start CodeKit if it is not running --language <name> With settings or defaults: which language (omit for project-wide) --extension <ext> With settings: which user-defined language --path <path> With settings set: which project (defaults to this directory) --values <json> With settings set, defaults set, or collections add/set: an object, for lists or explicit types --action <name> With files: compile, ignore, or copy --output-folder <path> With files set: write this file's output into this folder --output-name <name> With files set: what to call the output (needs --output-folder) --folders With files: include folders --shadow-items With files: include files imported from outside the project --limit <n> --offset <n> With files: read a large project a page at a time --clean With build: empty the Build Folder first, this once --install <lists> With packages: which lists to install from, comma-separated --save-to <lists> With packages: which lists to record in (empty for none) --exact / --no-exact With packages: record the exact version, or a range --package-lock With packages: write package-lock.json (--no-package-lock for not) --raise-limits With packages update: allow a breaking version --address <name> With preview: preferred, bonjour, lan, loopback, or localhost --browser <bundleID> With preview: e.g. com.apple.Safari --page <path> With preview: a path below the preview root --group <name> With move: which group --name <text> With rename, or with a groups subcommand --kind <name> With collections: hooks, buildSteps, webpPresets, or userLanguages --id <id> With collections: which row --type <name> With collections add: processItems, processRemainingItems, runScript --position <n> With collections move: where to put it, counting from zero
Exit Codes
0 finished, nothing failed 1 finished, something failed 2 bad arguments 3 CodeKit is not running (only with --no-launch) 4 the wait expired 5 understood and refused
A few things the CLI deliberately does not do: it can't add or remove the ESLint rules, Babel plugins, or Terser flags that CodeKit ships (it can change their settings), and a build step can't change its kind after it's created.
Hooks From The Command Line
Agents can create Hooks and decide which files trigger them, all in one request. A Hook is a row in the hooks collection with these fields, sent as JSON through --values:
name What the Hook is called enabled true or false scriptType Bash or AppleScript scriptSourceString The script itself matchExtensions List of extensions, with or without the dot: ["scss", ".css"] pathContains List of path fragments; a file must contain at least one pathDoesNotContain List of path fragments; a file must contain none of them matchesFormat A raw NSPredicate format string, for rules the lists can't express
The three list fields are compiled into the Hook's matching rule for you: (any listed extension) AND (any listed fragment) AND (no excluded fragment). Path fragments are compared case-insensitively. Setting any of the three replaces the whole rule, so send them together. For anything the lists can't say, use matchesFormat instead; it can't be combined with the list fields in the same request. The keys a file carries are inputFilename, inputFullPath, and inputAbbreviatedPath, and a format that can't be parsed or names other keys is refused rather than stored.
Create A Hook And Scope It In One Step
codekit collections add --kind hooks --values '{
"name": "Copy fonts",
"enabled": true,
"scriptSourceString": "cp \"$CK_INPUT_PATH\" ~/Sites/fonts/",
"matchExtensions": ["woff2", "woff"],
"pathDoesNotContain": ["node_modules"]
}'
A new Hook matches every file in the project until told otherwise, so always include a matching rule in the request that creates it. The reply includes the row's id, which is how you address it afterwards.
Change The Rule Later
codekit collections set --kind hooks --id <id> \
--values '{"matchesFormat": "inputFilename BEGINSWITH \"_\""}'
The listing reports each Hook's current rule as a sentence under matches, so an agent can read back what it set.
NOTE: A Hook script may launch background processes, but the build doesn't wait for them. CodeKit stops capturing the script's output three seconds after the script itself exits, so anything printed after that never reaches the log. Do the real work in the foreground.
Where It Lives
The tool is inside CodeKit's Application Support folder:
~/Library/Application Support/com.incident57.CodeKit3/bin/codekit
When you run Tasks > Install Agent Skills, CodeKit also links the tool into your PATH, so you can simply type codekit in Terminal. If you haven't, either call it by its full path or add that bin folder to your PATH yourself.
Learning The Commands
The reference above is a summary. For the notes that explain how CodeKit actually behaves (which files get rebuilt, when to pause watching, how settings tiers interact), run:
codekit --help
That prints every command and option plus notes worth reading. For the complete API, run codekit schema.
The older AppleScript API is still available, but the CLI covers far more of the app and is the better choice for new automation.
NOTE: Because the CLI is primarily intended for AI agents, which can adapt to changes instantly, I don't guarantee API stability in the CLI across CodeKit versions. Commands and syntax may change in future releases.