@zuke/chocolatey

`@zuke/chocolatey` — ship a prebuilt Windows binary through

Symbols

ChocoApikeyAction

type

type ChocoApikeyAction = list | add | remove

What choco apikey does: list the saved keys, save one, or remove one.

ChocoApikeySettings

class

class ChocoApikeySettings extends ChocoCommandSettings

Settings for choco apikey, which manages the API keys choco saves per source — so a later choco push to that source needs no key on its command line.

await ChocoTasks.apikey((s) =>
  s.add().source("https://push.chocolatey.org/").apiKey(key)
);

add needs a source and an apiKey; remove needs a source. With no action set, choco lists the saved keys (by source; it never prints a key itself).

Member	Signature	Doc
`list`	`list(): this`	List the saved keys' sources (`apikey list`).
`add`	`add(): this`	Save the `apiKey` for the `source` (`apikey add`).
`remove`	`remove(): this`	Remove the key saved for the `source` (`apikey remove`).
`source`	`source(url: string): this`	The source the key is for (`--source`).
`apiKey`	`apiKey(value: string): this`	The key to save (`--api-key`), for `add`. Masked in every rendering of the command and in its errors.

ChocoCommandSettings

class

class ChocoCommandSettings extends ChocoSettings

Base for a typed choco command: the command, then its operands, then its own options, then the common switches — the order choco's own usage lines print (choco install <pkg> [<options/switches>]). Anything added through the inherited .command(...)/.flag(...) escape hatches follows.

Valued options render as one --name=value token, the spelling choco's help prints, so a value that starts with - stays the option's value rather than becoming a switch of its own.

Operands are refused when choco would read them as a switch: a package id or file path never starts with -, and passing --force as a "package" would change what the command does rather than fail.

Member	Signature	Doc
`yes`	`yes(): this`	Answer yes to every prompt (`--yes`), which also accepts licenses.
`force`	`force(): this`	Force the behaviour (`--force`) — reinstall an installed package, say. Choco warns against it in normal operation.
`noProgress`	`noProgress(): this`	Do not print download progress percentages (`--no-progress`).
`limitOutput`	`limitOutput(): this`	Print only the essential information (`--limit-output`).
`verbose`	`verbose(): this`	Print verbose messages (`--verbose`).
`run`	`run(): Promise<CommandOutput>`	Run the command, masking every value passed to `secret` out of any `CommandError` or `CommandTimeoutError` it raises.

ChocoInstallSettings

class

class ChocoInstallSettings extends ChocoCommandSettings

Settings for choco install.

Member	Signature	Doc
`packages`	`packages(...ids: string[]): this`	Package ids to install (required); repeatable.
`source`	`source(location: string): this`	Where to find the packages (`--source`): a feed URL, or a local directory holding `.nupkg` files. Defaults to the configured feeds.
`version`	`version(value: string): this`	The exact version to install (`--version`).
`prerelease`	`prerelease(): this`	Consider prerelease versions (`--prerelease`).

ChocolateyPackage

interface

interface ChocolateyPackage

A rendered Chocolatey package: its identity, and the files that make it up, keyed by their path relative to the package directory — <id>.nuspec and tools/chocolateyinstall.ps1.

Plain data, so it can be written to disk, compared, or handed to ChocolateyTasks.verify and ChocolateyTasks.publish, which write it to a temporary directory and pack it there.

Member	Signature	Doc
`id`	`id: string`	The package id.
`version`	`version: string`	The package version.
`files`	`files: Readonly<Record<string, string>>`	Each file's content, keyed by its `/`-separated relative path.

ChocolateyPackageSettings

class

class ChocolateyPackageSettings

Settings for a package that installs a prebuilt binary from a zip.

Member	Signature	Doc
`id`	`id(value: string): this`	The package id (required), e.g. `app`: lowercase letters and digits, joined by single `.`, `-` or `_`, at most 100 characters. It is also the nuspec's file name, `<id>.nuspec`.
`version`	`version(value: string): this`	The package version (required), a NuGet version such as `1.2.3`, `1.2.3.4` or `1.2.3-beta.1` — usually the release's own version.
`title`	`title(value: string): this`	The display title (`<title>`), e.g. `App (Portable)`.
`authors`	`authors(...names: string[]): this`	The software's authors (`<authors>`, required); repeatable.
`owners`	`owners(...names: string[]): this`	The package's maintainers (`<owners>`) — on the community repository, the user names that may push it; repeatable.
`projectUrl`	`projectUrl(url: string): this`	The software's homepage (`<projectUrl>`, required; must be `https`).
`licenseUrl`	`licenseUrl(url: string): this`	The license's URL (`<licenseUrl>`, `https`) — the community repository requires it whenever the software has one.
`iconUrl`	`iconUrl(url: string): this`	The package icon's URL (`<iconUrl>`, `https`).
`packageSourceUrl`	`packageSourceUrl(url: string): this`	Where the package's own source lives (`<packageSourceUrl>`, `https`) — typically the repository whose build renders it.
`docsUrl`	`docsUrl(url: string): this`	The software's documentation (`<docsUrl>`, `https`).
`bugTrackerUrl`	`bugTrackerUrl(url: string): this`	The software's issue tracker (`<bugTrackerUrl>`, `https`).
`tags`	`tags(...values: string[]): this`	Search tags (`<tags>`), each one word; repeatable.
`copyright`	`copyright(text: string): this`	The software's copyright notice (`<copyright>`), one line — e.g. the line in its LICENSE, `Copyright (c) 2026 Acme`. The community repository's moderators ask for it whenever the software has one.
`summary`	`summary(text: string): this`	A one-line summary (`<summary>`).
`description`	`description(text: string): this`	The description (`<description>`, required; Markdown is fine), held to the community repository's length rules: 30 to 4000 characters.
`releaseNotes`	`releaseNotes(text: string): this`	The release notes (`<releaseNotes>`): text, Markdown, or a URL.
`url64bit`	`url64bit(url: string): this`	The 64-bit zip on the release (required; must be `https`) — what the install script downloads (`url64bit`) and unpacks into the package's `tools` directory, where choco shims every `.exe` it holds.
`checksum64`	`checksum64(sha256: string): this`	The zip's SHA-256 (required; 64 hex digits) — checked by choco before anything is unpacked (`checksum64`, with `checksumType64 = 'sha256'`).
`id_?`	`id_?: string`	The package id. Set by `id`.
`version_?`	`version_?: string`	The package version. Set by `version`.
`title_?`	`title_?: string`	The display title. Set by `title`.
`authors_`	`authors_: string[]`	The software's authors. Added by `authors`.
`owners_`	`owners_: string[]`	The package's maintainers. Added by `owners`.
`projectUrl_?`	`projectUrl_?: string`	The software's homepage. Set by `projectUrl`.
`licenseUrl_?`	`licenseUrl_?: string`	The license's URL. Set by `licenseUrl`.
`iconUrl_?`	`iconUrl_?: string`	The icon's URL. Set by `iconUrl`.
`copyright_?`	`copyright_?: string`	The copyright notice. Set by `copyright`.
`packageSourceUrl_?`	`packageSourceUrl_?: string`	Where the package's source lives. Set by `packageSourceUrl`.
`docsUrl_?`	`docsUrl_?: string`	The software's documentation. Set by `docsUrl`.
`bugTrackerUrl_?`	`bugTrackerUrl_?: string`	The software's issue tracker. Set by `bugTrackerUrl`.
`tags_`	`tags_: string[]`	The search tags. Added by `tags`.
`summary_?`	`summary_?: string`	The one-line summary. Set by `summary`.
`description_?`	`description_?: string`	The description. Set by `description`.
`releaseNotes_?`	`releaseNotes_?: string`	The release notes. Set by `releaseNotes`.
`url64bit_?`	`url64bit_?: string`	The 64-bit zip's URL. Set by `url64bit`.
`checksum64_?`	`checksum64_?: string`	The 64-bit zip's SHA-256. Set by `checksum64`.

ChocolateyPublishResult

interface

interface ChocolateyPublishResult

What a ChocolateyTasks.publish call pushed, and where.

Member	Signature	Doc
`source`	`source: string`	The source pushed to.
`nupkg`	`nupkg: string`	The file name of the `.nupkg` pushed, e.g. `app.1.2.3.nupkg`.

ChocolateyPublishSettings

class

class ChocolateyPublishSettings

Settings for publishing a package.

Member	Signature	Doc
`package`	`package(value: ChocolateyPackage): this`	The package to publish — what `ChocolateyTasks.package` rendered. It is packed in a temporary directory and the `.nupkg` pushed. Set this or `nupkg`, not both.
`nupkg`	`nupkg(path: PathLike): this`	A `.nupkg` already built, pushed as it is. Set this or `package`.
`apiKey`	`apiKey(value: string): this`	The source's API key — for the community repository, the one on `https://community.chocolatey.org/account`. Masked in every rendering of the push and in its errors. When unset, choco uses the key saved for the source with `choco apikey add`.
`source`	`source(url: string): this`	The source to push to (`https`), defaulting to the community repository, `https://push.chocolatey.org/`. An internal feed's push URL works too.
`toolPath`	`toolPath(path: PathLike): this`	The `choco` to run, when it is not on `PATH`.
`package_?`	`package_?: ChocolateyPackage`	The rendered package to pack and push. Set by `package`.
`nupkg_?`	`nupkg_?: string`	A `.nupkg` already built. Set by `nupkg`.
`apiKey_?`	`apiKey_?: string`	The API key. Set by `apiKey`.
`source_`	`source_: string`	The source to push to. Set by `source`.
`toolPath_?`	`toolPath_?: string`	The `choco` binary to run. Set by `toolPath`.

ChocolateyTasks

const

const ChocolateyTasks: ChocolateyTasksApi

Tasks for shipping a prebuilt Windows binary through Chocolatey.

ChocolateyTasksApi

interface

interface ChocolateyTasksApi

The shape of ChocolateyTasks.

Member	Signature	Doc
`package`	`package(configure: Configure<ChocolateyPackageSettings>): ChocolateyPackage`	The files of a package that installs a prebuilt binary from a zip on a release: `<id>.nuspec` and `tools/chocolateyinstall.ps1`. Pure: nothing is read or written.
`verify`	`verify(configure: Configure<ChocolateyVerifySettings>): Promise<void>`	Pack a rendered package in a temporary directory, install it from there, run the binary it puts on `PATH`, then uninstall it and remove the directory — the cleanup runs whether or not the install and check succeeded.
`publish`	`publish(configure: Configure<ChocolateyPublishSettings>): Promise<ChocolateyPublishResult>`	Push a package — rendered, or a `.nupkg` already built — to the community repository or another source, with its API key masked.
`verifyJob`	`verifyJob(configure: Configure<ChocolateyVerifyJobSettings>): CiInvocation`	The CI job that runs a verifying target on Windows runners, ready to list in `cicd({ invokes: [...] })`.

ChocolateyVerifyExpectation

type

type ChocolateyVerifyExpectation = unknown | unknown

What the binary's output must contain: the package version, or a text.

ChocolateyVerifyJobSettings

class

class ChocolateyVerifyJobSettings

Settings for the package-verification CI job.

Member	Signature	Doc
`target`	`target(value: TargetBuilder): this`	The target to run (required) — one that calls `ChocolateyTasks.verify`, or otherwise installs, checks and uninstalls the package.
`runners`	`runners(...labels: string[]): this`	The runner labels to verify on, replacing the default `windows-latest` — e.g. `"windows-2022", "windows-2025"` to cover both images. Each must be a Windows runner with Chocolatey installed.
`target_?`	`target_?: TargetBuilder`	The target the job runs. Set by `target`.
`runners_`	`runners_: string[]`	The runner labels the job fans out over. Set by `runners`.

ChocolateyVerifySettings

class

class ChocolateyVerifySettings

Settings for verifying a rendered package.

Member	Signature	Doc
`package`	`package(value: ChocolateyPackage): this`	The package to verify (required) — what `ChocolateyTasks.package` rendered.
`binary`	`binary(name: string): this`	The command the package puts on `PATH` (required), e.g. `app` — choco names each shim after the `.exe` it found in the zip.
`command`	`command(...args: string[]): this`	The arguments to run the binary with, e.g. `"--version"`.
`expectVersion`	`expectVersion(): this`	Require the binary's output to contain the package version.
`expectOutput`	`expectOutput(text: string): this`	Require the binary's output to contain `text`.
`toolPath`	`toolPath(path: PathLike): this`	The `choco` to run, when it is not on `PATH`.
`package_?`	`package_?: ChocolateyPackage`	The package to verify. Set by `package`.
`binary_?`	`binary_?: string`	The shim to run once installed. Set by `binary`.
`args_`	`args_: string[]`	The arguments to run it with. Set by `command`.
`expectation_?`	`expectation_?: ChocolateyVerifyExpectation`	What its output must contain. Set by `expectVersion`/`expectOutput`.
`toolPath_?`	`toolPath_?: string`	The `choco` binary to run. Set by `toolPath`.

ChocoPackSettings

class

class ChocoPackSettings extends ChocoCommandSettings

Settings for choco pack, which builds a .nupkg from a .nuspec. With no nuspec named, choco packs the one in the working directory.

Member	Signature	Doc
`nuspec`	`nuspec(path: PathLike): this`	The `.nuspec` to pack; defaults to the one in the working directory.
`version`	`version(value: string): this`	The version to write into the package, overriding the nuspec's (`--version`).
`outputDirectory`	`outputDirectory(path: PathLike): this`	Where to write the `.nupkg` (`--output-directory`); defaults to the working directory.

ChocoPushSettings

class

class ChocoPushSettings extends ChocoCommandSettings

Settings for choco push, which uploads a .nupkg to a source. With no package named, choco pushes the only .nupkg in the working directory.

The API key is an argument — choco reads it from nowhere else — so it is registered with the run's redactor and masked out of any error the push raises. It is still visible in the process table for the push's duration; on a shared host, save it once with choco apikey add instead and leave apiKey unset, and choco looks it up by source.

Member	Signature	Doc
`nupkg`	`nupkg(path: PathLike): this`	The `.nupkg` to push.
`source`	`source(url: string): this`	The source to push to (`--source`), e.g. `https://push.chocolatey.org/` for the community repository.
`apiKey`	`apiKey(value: string): this`	The source's API key (`--api-key`). Masked in every rendering of the command and in its errors.

ChocoSettings

class

class ChocoSettings extends SubcommandSettings

Settings for a choco invocation.

ChocoTasks

const

const ChocoTasks: ChocoTasksApi

Typed task functions for the Chocolatey choco CLI.

ChocoTasksApi

interface

interface ChocoTasksApi

The shape of ChocoTasks.

Member	Signature	Doc
`run`	`run(configure?: Configure<ChocoSettings>): Promise<CommandOutput>`	Run any `choco` command, built with `.command(...)`/`.flag(...)`.
`pack`	`pack(configure?: Configure<ChocoPackSettings>): Promise<CommandOutput>`	Build a `.nupkg` from a `.nuspec` (`choco pack`).
`push`	`push(configure?: Configure<ChocoPushSettings>): Promise<CommandOutput>`	Upload a `.nupkg` to a source (`choco push`); the API key is masked.
`install`	`install(configure: Configure<ChocoInstallSettings>): Promise<CommandOutput>`	Install packages (`choco install`).
`uninstall`	`uninstall(configure: Configure<ChocoUninstallSettings>): Promise<CommandOutput>`	Uninstall packages (`choco uninstall`).
`apikey`	`apikey(configure?: Configure<ChocoApikeySettings>): Promise<CommandOutput>`	List, save or remove a source's API key (`choco apikey`).

ChocoUninstallSettings

class

class ChocoUninstallSettings extends ChocoCommandSettings

Settings for choco uninstall.

Member	Signature	Doc
`packages`	`packages(...ids: string[]): this`	Package ids to uninstall (required); repeatable.
`source`	`source(location: string): this`	The source the packages came from (`--source`).
`version`	`version(value: string): this`	The installed version to uninstall (`--version`).
`allVersions`	`allVersions(): this`	Uninstall every installed version (`--all-versions`).