Other installation methods
Pin or customize the installer, use Homebrew or Go, verify release artifacts, and build Ptah from source.
The default installer is the shortest supported route. Use this page when you need a pinned version, a custom destination, a package manager, a manual verification trail, or a binary built from source.
Inspect the installer before running it
Section titled “Inspect the installer before running it”curl -fsSL https://ptah.run/install.sh -o install.shless install.shsh ./install.shirm https://ptah.run/install.ps1 -OutFile install.ps1Get-Content install.ps1 | more& ./install.ps1The downloaded files are the same scripts used by the one-line installer.
Pin or customize the release installer
Section titled “Pin or customize the release installer”Pin a release tag in automation:
curl -fsSL https://ptah.run/install.sh | sh -s -- --version vX.Y.ZPowerShell can pass the same choice through the environment when the script is
piped into iex:
$env:PTAH_INSTALL_VERSION = 'vX.Y.Z'irm https://ptah.run/install.ps1 | iexThe shell installer options and their environment equivalents are:
| Option | Environment variable | Result |
|---|---|---|
--version <tag> |
PTAH_INSTALL_VERSION |
Install one release instead of resolving the newest tag. |
--bin-dir <dir> |
PTAH_INSTALL_DIR |
Install into another directory. |
--only <list> |
PTAH_INSTALL_BINARIES |
Install a comma-separated subset of ptah, ptah-compat, and ptah-ls. |
--no-modify-path |
PTAH_INSTALL_NO_MODIFY_PATH |
Leave GitHub Actions and the Windows user Path unchanged. |
--verify-signature |
PTAH_INSTALL_VERIFY_SIGNATURE |
Verify checksums.txt with cosign and fail when cosign is unavailable. |
--dry-run |
PTAH_INSTALL_DRY_RUN |
Print the plan without downloading or writing. |
--quiet |
PTAH_INSTALL_QUIET |
Report errors only. |
| — | PTAH_INSTALL_BASE_URL |
Read release assets from a mirror. |
PowerShell spells the options -Version, -BinDir, -Only, -NoModifyPath,
-VerifySignature, -DryRun, and -Quiet. Run the saved script with -Help,
or the shell script with --help, for the current accepted values and exit
codes.
Boolean installer variables accept 1, 0, true, false, yes, or no.
An empty or unknown value is a configuration error rather than a silent default.
Both installers verify the archive against checksums.txt before they unpack
it, and refuse to install when the check cannot run. They install the Ptah
binaries only; a database provider is installed separately, as
Install a database provider describes.
Install with Homebrew
Section titled “Install with Homebrew”Install the newest tagged release on macOS or Linux with Homebrew:
brew install stokaro/ptah/ptahInstall the current master branch instead:
brew install --HEAD stokaro/ptah/ptah-edgeThe edge formula builds from source and therefore installs Go as a build dependency. It represents the development branch, not a released or signed archive. Refresh it explicitly with:
brew upgrade --fetch-HEAD ptah-edgeBoth formulas provide binaries with the same names. Remove one formula before
switching to the other so Homebrew does not leave the earlier links on PATH.
Install with the Go toolchain
Section titled “Install with the Go toolchain”Install the native CLI from a tagged module version:
go install ptah.run/cmd/ptah@vX.Y.ZInstall the compatibility binary and language server separately:
go install ptah.run/cmd/ptah-compat@vX.Y.Zgo install ptah.run/cmd/ptah-ls@vX.Y.ZThe binaries land in GOBIN, or in $(go env GOPATH)/bin when GOBIN is
unset. That directory is not automatically on PATH.
Build from a checkout
Section titled “Build from a checkout”git clone https://github.com/stokaro/ptah.gitcd ptahmake buildmake build writes ptah, ptah-compat, ptah-ls, and the integration-test
runner under bin/. The build uses the toolchain declared in go.mod.
Verify the source revision represented by the binary:
bin/ptah versionThe output names the exact commit and build date.
Install a release archive by hand
Section titled “Install a release archive by hand”Each release publishes one archive per supported host pair:
| Host | Archive pattern |
|---|---|
| Linux amd64 | ptah_<version>_linux_amd64.tar.gz |
| Linux arm64 | ptah_<version>_linux_arm64.tar.gz |
| macOS amd64 | ptah_<version>_darwin_amd64.tar.gz |
| macOS arm64 | ptah_<version>_darwin_arm64.tar.gz |
| Windows amd64 | ptah_<version>_windows_amd64.zip |
| Windows arm64 | ptah_<version>_windows_arm64.zip |
The tag includes a leading v; the archive’s embedded version does not. For
example, tag vX.Y.Z contains ptah_X.Y.Z_linux_amd64.tar.gz.
Download the archive and checksums.txt from the same release, then compare the
archive against the line that names it. On Linux:
sha256sum --ignore-missing -c checksums.txtOn macOS:
shasum -a 256 --ignore-missing -c checksums.txt--ignore-missing matters because the checksum file names every release asset,
while you downloaded only one archive. Stop if the matching line does not say
OK.
This comparison trusts checksums.txt as you downloaded it. To check that the
release workflow signed that file, verify its signature first, as
Verify the release signature shows.
The archive has no top-level directory. Extract it into a temporary directory,
then install the three binaries by name so LICENSE and README.md do not land
in the binary directory.
On macOS, how you download decides whether it runs
Section titled “On macOS, how you download decides whether it runs”The published macOS binaries are ad-hoc signed — the signature the Go linker writes when nothing signs the binary afterwards. Gatekeeper rejects that signature, and whether it ever looks depends on which tool fetched the archive.
curl and gh release download attach no com.apple.quarantine attribute, so
Gatekeeper never evaluates the binary and it runs. A browser download
attaches one, and the first run is refused with a system dialog titled
"ptah" Not Opened whose highlighted button is Move to Trash. There is no
Open Anyway in that dialog.
Measured on macOS 26.5 arm64 against ptah_0.3.0_darwin_arm64.tar.gz:
$ codesign -dv --verbose=4 ./ptahIdentifier=a.outSignature=adhocTeamIdentifier=not set
$ spctl --assess --type execute -vv ./ptah./ptah: rejectedTwo ways through. Fetch the archive with curl or gh release download rather
than a browser, which is what the commands on this page already do. Or, for an
archive a browser fetched, clear the attribute before the first run:
xattr -d com.apple.quarantine ptah ptah-compat ptah-lsClearing it says you trust the download, so verify the checksum and the release signature first — the two sections around this one are how.
Developer ID signing and notarization would make a browser download run with no
user action. They need an Apple Developer Program membership and a certificate
held as a repository secret, which is why this is documented rather than solved;
#2363 tracks it. Homebrew and
go install are unaffected, because neither attaches the attribute.
Verify the release signature
Section titled “Verify the release signature”The release workflow signs checksums.txt with Sigstore keyless signing. Each
release publishes the signature, the signing certificate and the transparency
log entry together as one bundle, checksums.txt.sigstore.json. Verifying it
with cosign checks two facts: the file is
unchanged since it was signed, and the signer was the release.yml workflow of
stokaro/ptah running for the tag you name.
Set TAG to the release you downloaded, fetch the checksum file and its bundle
from that release, and verify the checksum file:
TAG=vX.Y.Zcurl -fsSLO "https://github.com/stokaro/ptah/releases/download/$TAG/checksums.txt"curl -fsSLO "https://github.com/stokaro/ptah/releases/download/$TAG/checksums.txt.sigstore.json"cosign verify-blob \ --bundle checksums.txt.sigstore.json \ --certificate-identity "https://github.com/stokaro/ptah/.github/workflows/release.yml@refs/tags/$TAG" \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ checksums.txtcosign prints Verified OK and exits 0. It refuses a checksum file changed
after signing, a certificate issued to another workflow, repository or tag, and
a certificate from another OIDC issuer. Stop if it refuses.
Then compare the archive with its line in the verified checksum file. On Linux:
sha256sum --ignore-missing -c checksums.txtOn macOS:
shasum -a 256 --ignore-missing -c checksums.txtThe signature covers checksums.txt only, and the archive is trusted through
its line in that file, so a release needs both checks. Neither one says what
the binaries contain or how they were built. The SBOM files describe the
contents, and each one carries its own .sigstore.json bundle, which verifies
with the same command given the SBOM’s file names.
Container image
Section titled “Container image”The image contains ptah, ptah-compat, and ptah-ls in /usr/local/bin
for Linux amd64 and arm64. Its default entry point is ptah; select another
binary with --entrypoint:
docker run --rm ghcr.io/stokaro/ptah:0.11.2 versiondocker run --rm --entrypoint ptah-compat ghcr.io/stokaro/ptah:0.11.2 versiondocker run --rm --entrypoint ptah-ls ghcr.io/stokaro/ptah:0.11.2 --versiondocker.io/stokaro/ptah:0.11.2 mirrors the same image. To include Ptah Compat
in an existing migration image, copy its binary in a multi-stage build:
FROM stokaro/ptah:0.11.2 AS ptah-binFROM postgres:15-alpineCOPY --from=ptah-bin /usr/local/bin/ptah-compat /usr/local/bin/ptah-compatPin the image by digest
Section titled “Pin the image by digest”A tag such as X.Y.Z or latest is a name the registry resolves when you ask.
The registry can point it at another image after you read it, and latest
moves with every release. A digest names the bytes of one image index and
cannot change. The signature belongs to the digest, so resolve the tag once,
then verify, pull and deploy that one digest.
Read the digest a release tag names:
VERSION=X.Y.ZDIGEST="$(docker buildx imagetools inspect "ghcr.io/stokaro/ptah:$VERSION" --format '{{.Manifest.Digest}}')"echo "$DIGEST"The digest is the image index, the entry that lists the amd64 and arm64 images. Pin and verify the index. The release signs the index only, so the digest of one architecture’s manifest has no signature. Docker Hub serves the same digest for the same release.
Pull by digest from either registry:
docker pull "ghcr.io/stokaro/ptah@$DIGEST"docker pull "docker.io/stokaro/ptah@$DIGEST"Verify the image signature
Section titled “Verify the image signature”The release workflow signs the image index with Sigstore keyless signing, under
the same identity that signs checksums.txt. A signature is stored in the
registry beside the image it signs, so each registry carries its own, and the
release verifies both before it finishes. Verify the digest at the registry you
pull from, with cosign 3 or later.
For GHCR:
cosign verify \ --certificate-identity "https://github.com/stokaro/ptah/.github/workflows/release.yml@refs/tags/v$VERSION" \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ "ghcr.io/stokaro/ptah@$DIGEST"For Docker Hub:
cosign verify \ --certificate-identity "https://github.com/stokaro/ptah/.github/workflows/release.yml@refs/tags/v$VERSION" \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ "docker.io/stokaro/ptah@$DIGEST"cosign exits 0 and prints the verified claims on standard output as JSON. The
critical.image.docker-manifest-digest of each claim is $DIGEST. cosign
refuses a certificate issued to another workflow, repository or tag, a
certificate from another OIDC issuer, and a digest the release did not sign,
such as one architecture’s manifest or an image from another publisher. For a
digest that carries no signature at all, which includes the images of releases
published before image signing, it reports no signatures found. Stop if it
refuses.
cosign verify also accepts a tag, and then checks the digest the tag names at
that moment. That need not be the digest you pull a minute later, so verify
the digest you deploy.
To accept any release rather than one, name the identity as a regular expression anchored at both ends. An admission policy takes the same pattern:
cosign verify --certificate-identity-regexp '^https://github\.com/stokaro/ptah/\.github/workflows/release\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$' --certificate-oidc-issuer https://token.actions.githubusercontent.com "ghcr.io/stokaro/ptah@$DIGEST"A prerelease tag such as v1.2.3-rc.1 publishes images and signs them under
the same identity, so the optional - part matches it. Leave that part out of
the pattern to accept final releases only.
The signature says which workflow published the digest. It does not describe how the image was built: the release publishes no signed build provenance and makes no SLSA claim. Snapshot and pull-request builds are never pushed, so no such image exists to sign.
Install a database provider
Section titled “Install a database provider”An engine served by an executable provider, such as YDB through stokaro/ptah-ydb-plugin, needs that provider installed separately. No release archive, container image, Homebrew cask, installer script or GitHub Action carries one, so every installation channel takes the same step:
ptah providers install ydbThe command installs the newest provider release that works with this Ptah. A
provider declares the minimum provider contract version it needs, and Ptah
checks it against the contract version it speaks, so a provider release is not
tied to one Ptah release. --version installs a chosen release instead. The
command checks the download against the release’s checksums.txt, stores the
executable in your user cache directory, and records its SHA-256, which Ptah
checks before every start.
Once installed, the provider serves every command that names a ydb:// or
ydbs:// URL or the ydb dialect, with no flag. Ptah holds no YDB
implementation of its own, so without the provider such a command reports
provider_missing and the command that installs it.
With the provider installed, normal work needs no network. On a host that cannot
reach GitHub, install from an internal mirror with --download-base-url and
--version, or copy a verified executable to the host and select it in a
provider manifest. A container image installs the provider in a build step of
its own, as the user that runs the image. See
Test an executable provider.
Shell completion and editor support
Section titled “Shell completion and editor support”Generate shell completion from the installed native binary:
ptah completion --helpInstall the output using your shell’s normal completion directory. The command help provides the current Bash, Zsh, Fish, and PowerShell forms.
ptah-ls is included in release archives and by the default installer. See
Editor support for client
configuration.
Optional tools
Section titled “Optional tools”Some features call external programs:
- Graphviz
dotrenders SVG and image outputs from schema diagrams; - cosign verifies release signatures when requested;
- Docker is needed only for workflows whose chosen database or fixture runs in a container.
The default SQLite quick start needs none of them.
Verify the chosen route
Section titled “Verify the chosen route”Whichever route you use, finish with:
ptah versionptah-compat versionptah-ls --versionThen continue to the quick start.