# Command reference

Run commands from your application's directory. To select another configuration:

```sh
native-packages --config packaging/native-packages.yaml COMMAND
```

Use `native-packages --help` for a summary and `native-packages --version` for
the installed tool version. The examples below use app version `1.2.3`.

## init

Create `native-packages.yaml`:

```sh
native-packages init
native-packages init --interactive
native-packages init --name hello --input dist/hello.tar.gz --formats deb,rpm
```

The default is a Linux amd64 template. Setup uses available Cargo and Git
metadata. Review the inputs, library type, dependencies, and metadata before
building. Existing configuration is never overwritten. Interactive setup
requires a terminal and is unavailable in CI.

## validate

```sh
native-packages validate
```

Validate the configuration and render templates with placeholder values to
catch unknown tokens. This does not require actual build inputs or run hooks.

## doctor

```sh
native-packages doctor
native-packages doctor --target linux-amd64 --format deb
native-packages doctor --target macos-arm64 --defer-recipes
native-packages doctor --release v1.2.3
```

Check configuration and required tools for selected targets. Repeat `--target`
and `--format` for several selections. `--defer-recipes` omits recipe tools;
`--release` also checks for the download tool. Actual input and package checks
happen during `build`.

## build

```sh
native-packages build --version 1.2.3
native-packages build --release v1.2.3
```

| Option | Effect |
| --- | --- |
| `--version VERSION` | Set app version and use local inputs, unless `--release` is also present. |
| `--release TAG` | Download checked release inputs and use the tag's version. |
| `--target ID` | Select a target; repeat for several. |
| `--format FORMAT` | Select an output format; repeat for several. |
| `--output DIRECTORY` | Choose a new output directory. Default: `dist/packages/<version>`. |
| `--dry-run` | Print the plan without downloading, building, or executing hooks. |
| `--defer-recipes` | Build packages without acquiring global recipe assets or rendering templates. |

With neither version option, an exact supported release tag must exist at
`HEAD`. Supplying both requires matching versions. See
[Building packages](/building-packages/).

## aggregate

Combine build directories into a new output:

```sh
native-packages aggregate dist/linux dist/macos dist/windows --output dist/complete
```

`--output` is required. All inputs must have matching configuration, version,
and timestamp. The result must include every configured target and format.

For inputs made with `build --defer-recipes`, add `--finalize-recipes` to
render recipes using completed package hashes and remaining local assets.
See [Building across platforms](/multi-platform/).

## publish a build

```sh
native-packages publish --from dist/packages/1.2.3 --to github
native-packages publish --from dist/linux --to github --target linux-amd64
```

`--from` selects the build directory; `--to` lists destinations separated by
commas. `github` uploads release assets. Other names select entries or groups
in `repositories`.

The build must be complete and its recorded files unmodified. Repeated
`--target` options require exactly those targets, with all their formats.
Without target selection, all configured targets are required. There is no
publication `--format` or `--dry-run` option.

See [Publishing a release](/publishing/) for release setup and
upload behavior.

## Manage downstream recipes

| Command | Effect |
| --- | --- |
| `repositories` | List configured downstream destinations. |
| `stage TARGET DIRECTORY` | Stage generated recipes in the destination's local checkout. |
| `diff TARGET` | Show the staged changes. |
| `publish TARGET` | Commit and publish the staged update. |
| `status [TARGET]` | Query downstream versions and open requests; defaults to all. |

Here, `TARGET` means a repository destination or group, such as `aur`. It is
different from a build target such as `linux-amd64`.

For example:

```sh
native-packages stage aur dist/packages/1.2.3/recipes
native-packages diff aur
native-packages publish aur
native-packages status aur --offline --json
```

`status --offline` reads cached information; `--json` prints structured output.
Status exits unsuccessfully when a remote or request check fails.

For GitHub PR or GitLab MR destinations, `publish` requires `--body-file FILE`
with the reviewed submission description. It can also be used with
`publish --from ... --to DESTINATION`. Publish submission destinations
individually. See [Distribution recipes](/distribution-recipes/).

## notarize-macos

```sh
native-packages notarize-macos portable-input --output signed/hello
```

Copy a prepared macOS directory and, when Apple credentials are configured,
sign and notarize the copy. `--output` is required, must be new, and must be
outside the input. This command needs no project configuration. See
[Apple signing and notarization](/apple-notarization/).

## sign-windows

```sh
native-packages sign-windows target/x86_64-pc-windows-msvc/release/hello.exe dist/hello-setup.exe
```

Sign files in place with Azure Artifact Signing, with SHA-256 and an RFC 3161
timestamp, then check every signature. It needs the configuration's
`windows.signing` section, `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT`,
`AZURE_SIGNING_PROFILE`, and an Azure CLI sign-in, and runs on x64 Windows.
Use it for files built outside native-packages; MSI and Inno targets sign
their installers during `build`. See
[Windows code signing](/windows-signing/).

## Release checksums and signatures

```sh
native-packages release-checksums dist/release --output dist/release/checksums.txt
native-packages sign-checksums dist/release/checksums.txt --public-key assets/update-public-key.hex
native-packages verify-checksums dist/release/checksums.txt --public-key assets/update-public-key.hex
```

These commands need no project configuration. Generation requires a nonempty,
flat directory of regular files and a new output file in that directory.
Signing checks every listed artifact before writing a new `checksums.txt.sig`.
Verification requires both a valid signature and matching artifact hashes.

The signing key comes from `NATIVE_PACKAGES_SIGNING_KEY`, or the environment
variable named by `--key-env VARIABLE`. Pass only the variable's name on the
command line, never its secret value. The public-key file contains 64 hex digits.
See [Release signatures and attestations](/release-signing/).

## migrate

```sh
native-packages migrate --dry-run
native-packages migrate
```

Preview or create a single configuration from the legacy `packaging/project.yml`
setup. Existing packaging files are preserved.

## check-version

```sh
native-packages check-version v1.2.3
```

Validate a stable tag and, when `version_file` is configured, compare it with
the application's Cargo manifest version. Set `version_section` for workspace
manifests.

## omarchy-recipe

```sh
native-packages omarchy-recipe ../omarchy-pkgs --release v1.2.3 [--package hello-bin]
```

Write `pkgbuilds/NAME-bin/` in an omacom/omarchy-pkgs checkout from the
`arch/NAME-bin/` templates, rendered for that published release with
`pkgrel=1` and the hashes from `release.checksums`. Source URLs are rewritten
to follow `pkgver`, and `.omarchy/package.json` declares an `upstream.watch` on
the GitHub releases, so Omarchy's bot can update the package. The command downloads only the checksum manifest.
`--package` is required when several `-bin` templates exist. It refuses an
existing recipe directory. See [Omarchy packages](/omarchy/).

## Select an installed tool version

If several gem versions are installed, RubyGems lets you select the one required
by the configuration:

```sh
native-packages _0.11.0_ build --version 1.2.3
```

Bundler also works if you prefer to manage the gem in a Gemfile.

## Legacy commands

`prepare`, `check`, `artifacts`, `publish-release`, and `publish-aur` remain
available for older projects. Their original workflow is documented in the
[legacy guide](https://github.com/crmne/native-packages/blob/main/docs/legacy.md).
Use `build` and `publish --from` for new configurations.

Command reference

Run commands from your application’s directory. To select another configuration:

native-packages --config packaging/native-packages.yaml COMMAND

Use native-packages --help for a summary and native-packages --version for the installed tool version. The examples below use app version 1.2.3.

init

Create native-packages.yaml:

native-packages init
native-packages init --interactive
native-packages init --name hello --input dist/hello.tar.gz --formats deb,rpm

The default is a Linux amd64 template. Setup uses available Cargo and Git metadata. Review the inputs, library type, dependencies, and metadata before building. Existing configuration is never overwritten. Interactive setup requires a terminal and is unavailable in CI.

validate

native-packages validate

Validate the configuration and render templates with placeholder values to catch unknown tokens. This does not require actual build inputs or run hooks.

doctor

native-packages doctor
native-packages doctor --target linux-amd64 --format deb
native-packages doctor --target macos-arm64 --defer-recipes
native-packages doctor --release v1.2.3

Check configuration and required tools for selected targets. Repeat --target and --format for several selections. --defer-recipes omits recipe tools; --release also checks for the download tool. Actual input and package checks happen during build.

build

native-packages build --version 1.2.3
native-packages build --release v1.2.3

Option	Effect
`--version VERSION`	Set app version and use local inputs, unless `--release` is also present.
`--release TAG`	Download checked release inputs and use the tag’s version.
`--target ID`	Select a target; repeat for several.
`--format FORMAT`	Select an output format; repeat for several.
`--output DIRECTORY`	Choose a new output directory. Default: `dist/packages/<version>`.
`--dry-run`	Print the plan without downloading, building, or executing hooks.
`--defer-recipes`	Build packages without acquiring global recipe assets or rendering templates.

With neither version option, an exact supported release tag must exist at HEAD. Supplying both requires matching versions. See Building packages.

aggregate

Combine build directories into a new output:

native-packages aggregate dist/linux dist/macos dist/windows --output dist/complete

--output is required. All inputs must have matching configuration, version, and timestamp. The result must include every configured target and format.

For inputs made with build --defer-recipes, add --finalize-recipes to render recipes using completed package hashes and remaining local assets. See Building across platforms.

publish a build

native-packages publish --from dist/packages/1.2.3 --to github
native-packages publish --from dist/linux --to github --target linux-amd64

--from selects the build directory; --to lists destinations separated by commas. github uploads release assets. Other names select entries or groups in repositories.

The build must be complete and its recorded files unmodified. Repeated --target options require exactly those targets, with all their formats. Without target selection, all configured targets are required. There is no publication --format or --dry-run option.

See Publishing a release for release setup and upload behavior.

Manage downstream recipes

Command	Effect
`repositories`	List configured downstream destinations.
`stage TARGET DIRECTORY`	Stage generated recipes in the destination’s local checkout.
`diff TARGET`	Show the staged changes.
`publish TARGET`	Commit and publish the staged update.
`status [TARGET]`	Query downstream versions and open requests; defaults to all.

Here, TARGET means a repository destination or group, such as aur. It is different from a build target such as linux-amd64.

For example:

native-packages stage aur dist/packages/1.2.3/recipes
native-packages diff aur
native-packages publish aur
native-packages status aur --offline --json

status --offline reads cached information; --json prints structured output. Status exits unsuccessfully when a remote or request check fails.

For GitHub PR or GitLab MR destinations, publish requires --body-file FILE with the reviewed submission description. It can also be used with publish --from ... --to DESTINATION. Publish submission destinations individually. See Distribution recipes.

notarize-macos

native-packages notarize-macos portable-input --output signed/hello

Copy a prepared macOS directory and, when Apple credentials are configured, sign and notarize the copy. --output is required, must be new, and must be outside the input. This command needs no project configuration. See Apple signing and notarization.

sign-windows

native-packages sign-windows target/x86_64-pc-windows-msvc/release/hello.exe dist/hello-setup.exe

Sign files in place with Azure Artifact Signing, with SHA-256 and an RFC 3161 timestamp, then check every signature. It needs the configuration’s windows.signing section, AZURE_SIGNING_ENDPOINT, AZURE_SIGNING_ACCOUNT, AZURE_SIGNING_PROFILE, and an Azure CLI sign-in, and runs on x64 Windows. Use it for files built outside native-packages; MSI and Inno targets sign their installers during build. See Windows code signing.

Release checksums and signatures

native-packages release-checksums dist/release --output dist/release/checksums.txt
native-packages sign-checksums dist/release/checksums.txt --public-key assets/update-public-key.hex
native-packages verify-checksums dist/release/checksums.txt --public-key assets/update-public-key.hex

These commands need no project configuration. Generation requires a nonempty, flat directory of regular files and a new output file in that directory. Signing checks every listed artifact before writing a new checksums.txt.sig. Verification requires both a valid signature and matching artifact hashes.

The signing key comes from NATIVE_PACKAGES_SIGNING_KEY, or the environment variable named by --key-env VARIABLE. Pass only the variable’s name on the command line, never its secret value. The public-key file contains 64 hex digits. See Release signatures and attestations.

migrate

native-packages migrate --dry-run
native-packages migrate

Preview or create a single configuration from the legacy packaging/project.yml setup. Existing packaging files are preserved.

check-version

native-packages check-version v1.2.3

Validate a stable tag and, when version_file is configured, compare it with the application’s Cargo manifest version. Set version_section for workspace manifests.

omarchy-recipe

native-packages omarchy-recipe ../omarchy-pkgs --release v1.2.3 [--package hello-bin]

Write pkgbuilds/NAME-bin/ in an omacom/omarchy-pkgs checkout from the arch/NAME-bin/ templates, rendered for that published release with pkgrel=1 and the hashes from release.checksums. Source URLs are rewritten to follow pkgver, and .omarchy/package.json declares an upstream.watch on the GitHub releases, so Omarchy’s bot can update the package. The command downloads only the checksum manifest. --package is required when several -bin templates exist. It refuses an existing recipe directory. See Omarchy packages.

Select an installed tool version

If several gem versions are installed, RubyGems lets you select the one required by the configuration:

native-packages _0.11.0_ build --version 1.2.3

Bundler also works if you prefer to manage the gem in a Gemfile.

Legacy commands

prepare, check, artifacts, publish-release, and publish-aur remain available for older projects. Their original workflow is documented in the legacy guide. Use build and publish --from for new configurations.