PostMyForm CLI

Install the PostMyForm CLI

The PostMyForm CLI manages forms through the public PostMyForm API.

The examples on this page match release v0.1.2.

Use the canonical public project for source, releases, checksums, and package-specific details:

The current release provides native binaries for:

| Platform | Architecture | Release file | | --- | --- | --- | | Linux | amd64 | postmyform-linux-amd64 | | Linux | arm64 | postmyform-linux-arm64 | | macOS | amd64 | postmyform-darwin-amd64 | | macOS | arm64 | postmyform-darwin-arm64 | | Windows | amd64 | postmyform-windows-amd64.exe |

Each release also provides SHA256SUMS. Verify the downloaded binary before installing it.

Linux

Download the binary that matches your architecture and SHA256SUMS.

For Linux amd64 with GitHub CLI:

gh release download \
  --repo PostMyForm/postmyform-cli \
  --pattern postmyform-linux-amd64 \
  --pattern SHA256SUMS

sha256sum -c --ignore-missing SHA256SUMS

chmod +x postmyform-linux-amd64
sudo install -m 0755 postmyform-linux-amd64 /usr/local/bin/postmyform

Use postmyform-linux-arm64 on Linux arm64.

macOS

Download the binary that matches your Mac architecture and SHA256SUMS.

For Apple Silicon:

shasum -a 256 postmyform-darwin-arm64
chmod +x postmyform-darwin-arm64
sudo install -m 0755 postmyform-darwin-arm64 /usr/local/bin/postmyform

Compare the SHA-256 result with the matching entry in SHA256SUMS.

Use postmyform-darwin-amd64 on an Intel Mac.

Windows

Download:

postmyform-windows-amd64.exe

Verify it in PowerShell:

Get-FileHash .\postmyform-windows-amd64.exe -Algorithm SHA256

Compare the result with the matching entry in SHA256SUMS.

You can rename the executable to postmyform.exe and place it in a directory included in your PATH.

Verify the installed version

Run:

postmyform --version

Compare the installed version with the latest release published in the PostMyForm CLI releases.

The CLI does not update itself automatically.

Authenticate safely

Create an API credential for the access that the CLI needs.

Use:

forms:read for read operations;
forms:write for create, update, and field-replacement operations.

Do not put an API token in a command-line argument or URL.

For a temporary Bash shell, read the token without echoing it or placing the token value in shell history:

read -rsp "PostMyForm API token: " POSTMYFORM_API_TOKEN
echo
export POSTMYFORM_API_TOKEN

The CLI reads the credential from POSTMYFORM_API_TOKEN.

When you finish using the CLI, remove the token from the shell environment:

unset POSTMYFORM_API_TOKEN

Do not commit API credentials to source control or place them in screenshots, logs, or documentation.

API endpoint

The CLI uses the production API by default:

https://postmyform.com/api/v1

Most users should not set a different endpoint.

For an approved alternate environment, the CLI also supports POSTMYFORM_API_BASE_URL.

Remote API endpoints must use HTTPS. Plain HTTP is accepted only for loopback addresses during local testing.

CLI operations

The released CLI supports seven form operations.

List forms

postmyform forms list

Use structured output when needed:

postmyform forms list --json

Create a form

A form requires a name and destination email.

postmyform forms create \
  --name "Contact" \
  --destination-email "contact@example.com" \
  --allowed-origin "https://example.com"

Repeat --allowed-origin to add more than one allowed origin.

Use --json when a script needs structured output.

Get a form

postmyform forms get FORM_ID

For JSON:

postmyform forms get FORM_ID --json

FORM_ID is the form UUID returned by PostMyForm.

Update a form

postmyform forms update FORM_ID \
  --name "Support Contact"

The released command can update selected form properties, including the name, destination email, allowed origins, success redirect, spam honeypot field, and status.

Only options supplied to the command are included in the update.

Get form fields

postmyform forms fields get FORM_ID

For JSON:

postmyform forms fields get FORM_ID --json

Replace form fields

fields replace replaces the complete ordered field collection. It does not append fields.

From a file:

postmyform forms fields replace FORM_ID \
  --file fields.json

Or from standard input:

cat fields.json | postmyform forms fields replace FORM_ID --file -

The input is validated before the mutation is sent.

Get generated form HTML

Print the generated HTML:

postmyform forms snippet FORM_ID

Write it to a file:

postmyform forms snippet FORM_ID > form.html

The CLI prints the HTML returned by PostMyForm. It does not execute the generated HTML.

End-to-end example

Create a form with JSON output:

postmyform forms create \
  --name "Contact" \
  --destination-email "contact@example.com" \
  --allowed-origin "https://example.com" \
  --json

Copy the returned form ID, then request the generated HTML:

postmyform forms snippet FORM_ID > form.html

Add the generated form HTML to your static site and publish it.

You do not need dashboard-specific steps to manage the form through the CLI.

JSON output and exit codes

Commands that support structured output use --json.

JSON data is written to standard output. Errors are written to standard error.

The released CLI uses these exit codes:

| Code | Meaning | | ---: | --- | | 0 | Success | | 2 | Invalid command, option, input, or local configuration | | 3 | Authentication or authorization failure | | 4 | PostMyForm API or response failure | | 5 | Network or transport failure |

Automation should test the exit code rather than parse human-readable error messages.

The CLI does not automatically retry mutations.

API details

For raw HTTP requests, request and response schemas, authentication details, and the supported API contract, use the PostMyForm API reference.

The public OpenAPI document is available at https://postmyform.com/openapi.json.

For release-specific installation, checksum, attestation, upgrade, and development details, use the canonical PostMyForm CLI repository.