CLI Reference

Wick ships two kinds of commands:

• Built-in commands are hardcoded in the wick binary (init, run, build, server, worker, all, skill, doctor, mcp, workflow, upgrade, version). They work the same across every project and the behavior is fixed by the installed wick version.
• Task shortcuts (dev, setup, test, tidy, generate) are thin wrappers that execute the matching task in your project's wick.yml. You can edit or extend those tasks per project; wick run <task> runs any arbitrary task defined there.

Apps built by wick build also ship their own subcommand tree (tray, server, worker, all, start, stop, status, service, config, mcp, uninstall) — see the dedicated App CLI Reference.

Run wick --help to print the current list.

---

Built-in commands

wick init [name]

Scaffold a new wick project in ./<name> (default: myapp).

wick init my-app
wick init my-app --skip-setup   # skip "go mod tidy" and "wick setup"

Copies the bundled template — tools, jobs, connectors, tags, wick.yml, AGENTS.md, example tool, example job, and the example crudcrud connector — plus the bundled skills (tool-module, connector-module, design-system) into ./.claude/skills/.

---

wick run <task>

Execute an arbitrary task from wick.yml. Useful for tasks that don't have a dedicated shortcut.

wick run css        # runs the "css" task from wick.yml
wick run clean

Shortcuts below (dev, setup, etc.) are equivalent to wick run <name>.

---

wick skill list

List the AI agent skills bundled with the installed wick binary.

$ wick skill list
connector-module
tool-module
design-system

---

wick skill sync [name...]

Replace ./.claude/skills/<name>/ with the bundled version. Use this after upgrading wick to pull in updated skill content.

wick skill sync                                # sync all bundled skills
wick skill sync design-system                  # sync one
wick skill sync tool-module connector-module   # sync several

Side effects on ./AGENTS.md:

• Missing — a fresh AGENTS.md is written from the bundled template (same file shipped by wick init).
• Present, skill table matches the default shape — the body of the | Task | Skill | table is regenerated from the bundled skill list. Labels for known skills come from wick's internal map; unknown skills fall back to the skill name.
• Present, skill table is customized (rows don't link to ./.claude/skills/<name>/SKILL.md) — left untouched. Edit by hand if you want the new skills listed.

The skill folder contents are always replaced — local edits inside ./.claude/skills/<name>/ will be overwritten. Commit anything you want to keep.

---

wick build

Compile the project to a Go binary with version metadata baked in via Go ldflags, then wrap it into the platform-native distributable (.exe / .dmg / .deb). Reads name: and version: from wick.yml by default; flags / env vars override.

wick build                                 # → bin/<name>-<goos>-<goarch>[.exe] + native bundle
wick build --target linux/arm64            # cross-compile via shorthand
wick build --goos linux --goarch arm64     # cross-compile via explicit flags
wick build --all                           # build every target the host can produce
wick build -o custom/path                  # rename the raw binary (bundle name unaffected)
wick build --headless                      # drop tray UI (-tags headless)
GOOS=linux GOARCH=arm64 wick build         # cross-compile via env (CI flow)

Common flags:

Flag	Env fallback	Effect
--app-name	APP_NAME	Override name: from wick.yml
--app-version	APP_VERSION	Override version: from wick.yml
--release-github-pat	RELEASE_GITHUB_PAT	Bake releases PAT for self-updater
--release-github-repo	RELEASE_GITHUB_REPOSITORY	Bake releases repo owner/repo for self-updater
-o, --output	—	Raw binary path (default bin/<name>-<goos>-<goarch>[.exe]); bundle is written next to it
-t, --target	—	Target shorthand <os>/<arch> (e.g. linux/arm64); mutex with --goos/--goarch
--goos	GOOS	Target GOOS; mutex with --target
--goarch	GOARCH	Target GOARCH; mutex with --target
--all	—	Best-effort build all OS/arch; auto-skip darwin on non-mac host
--headless	—	Add -tags headless (no tray) — recommended for Termux / server targets

Full reference incl. CI workflow templates and PAT setup: wick build reference.

---

wick server

Start the HTTP server directly without needing a wick.yml task. Equivalent to go run . server.

wick server
wick server --host 127.0.0.1     # bind specific interface
wick server --host 192.168.1.42  # multi-NIC host: bind one IP only
wick server --localhost          # shortcut for --host 127.0.0.1

--host / --localhost forward to the inner go run . server, which sets WICK_HOST and makes the kernel drop SYN packets from any non-matching source. See <app> server for the full rationale, precedence rules, and SSH port-forward pattern.

Use this instead of wick dev when you don't need hot-reload or asset generation — production-like run from source.

---

wick worker

Start the background job worker directly without needing a wick.yml task. Equivalent to go run . worker.

wick worker

Runs the same worker process as ./myapp worker but straight from source. Useful for running server and worker in separate terminals during development.

---

wick all

Start the HTTP server and the cron scheduler in one process. Equivalent to go run . all. See <app> all on the App CLI page for the single-node vs. multi-pod trade-off table — same command, just running from source instead of a built binary.

wick all
wick all --host 127.0.0.1   # bind specific interface
wick all --localhost        # shortcut for --host 127.0.0.1

---

wick mcp

Wick's own MCP server, separate from the per-app MCP a built binary ships (<app> mcp). Used while developing tools / connectors in the wick repo so a Claude / Cursor session can hit the live in-tree code without going through wick build.

wick mcp serve                                # run over stdio (called by clients)
wick mcp config                               # print a config snippet + target paths
wick mcp install --client claude              # write the entry directly
wick mcp install --client all --mode rebuild  # all clients, force rebuild on launch

Build modes (--mode, also accepted by mcp serve):

Mode	When to use
auto (default)	Rebuild only when HEAD commit changed; otherwise run cached binary
dev	go run — no binary, always recompiles, good while actively developing
build	Build once if binary missing, reuse existing binary otherwise
rebuild	Always force a full rebuild before running

--client accepts claude, cursor, gemini, codex, claude-code, all. Default server name is the basename of the cwd; override with --name.

---

wick workflow test <id>

Run the __tests__/ fixtures bundled with a workflow under the current agents layout. Walks every case file in <workflow_id>/__tests__/, executes the workflow against each, and prints pass / fail counts.

wick workflow test draft-pr
#   ✓ happy-path (412ms)
#   ✓ missing-input-rejected (88ms)
#   ✗ on-error-branch
#     expected status="failed", got "succeeded"

Exits non-zero if any case fails. Useful in CI to gate workflow edits.

---

wick doctor [binary]

Run a sequence of environment checks and print a summary. Each line reports ✓ (ok), ✗ (missing / broken), or ! (warning). Exit code 0 when all required checks pass, 1 otherwise.

wick doctor                    # check the wick binary itself
wick doctor wick-lab.exe       # inspect a specific branded build

When you pass a binary path, doctor derives that build's AppName, locates the matching <app>-gate sidecar, and verifies socket / spec paths line up. Useful when you've shipped a branded MSI / .deb and want to confirm the Command Gate is wired up before users see it.

The gate-specific checks are detailed in the Command Gate guide.

---

wick upgrade

Upgrade the wick CLI binary and the github.com/yogasw/wick dependency in the current project's go.mod to the latest released version, then tidy. Prompts before each step; pass -y to skip all prompts.

wick upgrade          # interactive — confirms each step
wick upgrade --yes    # non-interactive — assumes yes to all prompts
wick upgrade -y       # same, short form

Example session (interactive):

$ wick upgrade
upgrade cli binary v0.1.13 -> v0.4.2? [Y/n]: y
upgrade go.mod dep v0.1.13 -> v0.4.2? [Y/n]: y
> go get github.com/yogasw/wick@v0.35.3
> go mod tidy
Dockerfile: wick@v0.1.13 -> v0.4.2? [Y/n]: y

Flags:

Flag	Short	Default	Description
--yes	-y	false	Assume yes to all confirmation prompts

Steps:

1. Read the installed CLI binary version and the pinned version from ./go.mod.
2. Fetch the latest version from https://proxy.golang.org/github.com/yogasw/wick/@latest.
3. If CLI binary is stale (or dev), prompt to reinstall it.
4. If go.mod dep is stale, prompt to run go get + go mod tidy.
5. If a Dockerfile in the current directory references an older wick version, prompt to update it.

Each prompt defaults to yes (press Enter to accept). Pass -y/--yes to skip all prompts non-interactively (useful in scripts or CI).

Run from a project directory (one that has a go.mod requiring github.com/yogasw/wick).

---

wick version

Print the installed wick version.

$ wick version
v0.1.12

wick version next

Bump the last numeric segment of version: in ./wick.yml by one, write the file back in place (preserving quotes / trailing comments / formatting), and print the new value to stdout.

$ cat wick.yml | grep '^version:'
version: 0.6.4
$ wick version next
0.6.5
$ cat wick.yml | grep '^version:'
version: 0.6.5

Current version:	After wick version next
1	2
0.1	0.2
0.6.4	0.6.5
1.2.3.4	1.2.3.5
"0.1.0"	"0.1.1" (quotes preserved)

Errors out if wick.yml has no version: line with a numeric value, or the last segment is not an integer.

Used by release.yml when AUTO_VERSION=true — prepare calls it to resolve the next tag, release calls it again on a fresh checkout (idempotent — same baseline, same bump) to commit the diff back to the source branch.

---

wick plugin build

Compile connector plugins from a plugins-style monorepo and pack each binary plus its auto-generated manifest (plugin.json) into a release zip: <name>-<version>-<goos>-<goarch>.zip.

Run this from the root of a plugins monorepo where plugins live under connector/<name>/main.go.

wick plugin build gmail slack           # build specific plugins for the host arch
wick plugin build --all-plugins         # every folder under connector/
wick plugin build --changed             # only folders changed since origin/main
wick plugin build --all-plugins --all   # all plugins × all OS/arch targets
wick plugin build gmail --sign-key wick.key   # sign the manifest with an ed25519 key

Common flags:

Flag	Default	Effect
--kind	connector	Source folder kind: connector, tool, or job
--target	host	Single target or comma-separated list, e.g. linux/arm64,darwin/amd64
--goos / --goarch	—	Split form of --target; mutually exclusive with it
--all	false	Build all supported targets (linux/arm64, linux/amd64, darwin/arm64, darwin/amd64, windows/amd64)
--all-plugins	false	Build every plugin folder under <kind>/ (skip _-prefixed scaffolds)
--changed	false	Build only folders whose files changed since --since
--since	origin/main	Git ref to diff against for --changed
--sign-key	—	Path to an ed25519 private key; signs each manifest. Generate with cmd/plugin-keygen.
--cosign-key	—	Path to a cosign private key; signs each binary via the external cosign CLI
-o, --output	bin	Output directory for the zip files

The manifest (plugin.json) is generated from the freshly-built binary via --dump-manifest, so the manifest can never drift from the binary it describes.

See also the consumption side: <app> plugin commands on the running binary.

---

wick plugin catalog

Regenerate the marketplace catalog (plugins.json) from GitHub releases. This is the Go, struct-typed replacement for the jq pipeline that previously built the catalog in CI. The generated JSON uses the same Available shape the app reads, so the catalog can never drift from what the app parses.

wick plugin catalog --repo owner/plugins-repo --out plugins/plugins.json
wick plugin catalog --repo owner/plugins-repo -o -    # write to stdout

Flag	Default	Effect
--repo	—	GitHub repo as owner/name (required)
--token	—	GitHub token (env: GITHUB_TOKEN); optional for public repos, raises rate limit from 60 to 5 000 req/hr
-o, --out	plugins/plugins.json	Output path; - writes to stdout

The command pages through all releases in the repo, keeps the highest semver version per plugin key, maps each zip asset to its OS/arch download URL, and lifts Name/Description from the plugin manifest inside the first release zip.

Tag convention: plugin releases are tagged <key>/v<version> (e.g. slack/v0.2.1). Core wick releases (v<version>, no slash) are ignored.

---

Task shortcuts (from wick.yml)

Each of these runs the matching task in wick.yml. The commands shown in the "Default behavior" column are what the template ships — edit wick.yml to change them.

Command	Default behavior
wick setup	Download Tailwind + templ into ./bin/, run go mod tidy
wick dev	Generate templ + CSS, start go run . server
wick generate	Regenerate templ, run go generate ./..., rebuild CSS
wick test	go test ./... -coverprofile=./coverage.out
wick tidy	go fmt ./... + go mod tidy -v

wick build auto-runs generate

If wick.yml defines a generate task, wick build runs it before the Go compile step — keeps templ + CSS + go generate in sync without a separate task wrapper. Skip it by removing or renaming the task.

See wick.yml reference for the full task syntax (if_missing, download, bg, variable interpolation, etc.).

---

See also

• App CLI Reference — subcommands of the binary wick build produces (tray, server, start, stop, service, config, mcp, uninstall).
• Desktop Tray guide — what the tray menu does and how its autostart toggle relates to <app> service install.
• Termux / Android guide — running wick headless via the start / service install flow.