Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

piquelctl commands

This page lists every piquelctl command with its arguments and options. It is generated from the same definitions as piquelctl --help, so --help on any command prints the same text. For how to install the CLI, connect it to a daemon, and read its output, see piquelctl. The user guide shows the commands at work.

Every command also accepts -h (a summary) and --help (everything below), and piquelctl --version prints the CLI’s version.

piquelctl

Operate a piqueld control plane.

piquelctl connects to the daemon’s Unix socket, /run/piqueld/piqueld.sock, unless --socket, --url, the PIQUELD_SOCKET or PIQUELD_URL variable, or a connection profile names another endpoint. It authenticates with PIQUELD_TOKEN, or with the login that piquelctl login saved. On the daemon host, root and the daemon’s user need no login.

piquelctl [OPTIONS] <COMMAND>

Global options:

  • --profile <NAME>: Connect with this profile from the profiles files.

    Defaults to PIQUELD_PROFILE, else to the profile named by the profiles file’s top-level default, else to the profile named default if there is one.

  • --profiles-file <PATH>: Read profiles only from this file.

    Defaults to PIQUELD_PROFILES_FILE. Without either, piquelctl reads /etc/piqueld/profiles.toml, then ~/.config/piqueld/profiles.toml (in $XDG_CONFIG_HOME when it is set), whose profiles replace those of the same name.

  • --socket <PATH>: Connect to the daemon’s Unix socket at this path.

    It overrides PIQUELD_SOCKET, PIQUELD_URL and the profile’s endpoint. Without any of them, piquelctl uses /run/piqueld/piqueld.sock.

  • --account <ACCOUNT>: Act as this saved login, by username or account ID.

    Defaults to the login you saved last for this daemon. PIQUELD_TOKEN takes precedence over saved logins.

  • --allow-insecure-http: Allow sending credentials over plain HTTP to a remote daemon.

    Only use it when something else encrypts the connection, such as Tailscale: piquelctl adds no encryption and doesn’t check. HTTPS, loopback addresses and the Unix socket don’t need it.

  • --url <URL>: Connect to the daemon over HTTP or HTTPS at this address.

    Give an origin without a path, query or credentials, such as http://127.0.0.1:7845 or https://piqueld.example.ts.net. It overrides PIQUELD_URL, PIQUELD_SOCKET and the profile’s endpoint.

  • --timeout <DURATION>: Give up on the command after this long, such as 500ms, 30s, 2m or 1h.

    A number without a unit is seconds. The limit also applies to each request. Confirmation prompts don’t count towards it, and it doesn’t limit the session of app exec and preview exec, or how long login waits for your approval. PIQUELD_TIMEOUT and a profile’s timeout replace the default. Default: 30s.

  • --json: Print the result as JSON on standard output.

    Information, warnings and errors on standard error become one JSON object per line.

  • -q, --quiet: Hide human-readable results, information and progress.

    JSON results, warnings, errors and prompts still appear.

  • --noninteractive: Never prompt, even on a terminal.

    Commands that ask for confirmation then fail unless you pass --yes.

Commands:

  • piquelctl login: Sign in with a passkey through your browser, and save the login.
  • piquelctl logout: Sign out: revoke the current credential and delete its saved copy.
  • piquelctl whoami: Show who you are signed in as and what the current credential may do.
  • piquelctl account: Manage accounts: list, edit and delete them, change their grants and passkeys, and create and revoke invitation and enrollment links.
  • piquelctl token: Create, list and revoke your API tokens and sessions, or revoke an account’s.
  • piquelctl audit: Read the audit trail of API requests, newest first.
  • piquelctl recover-admin: Print a one-time link that creates a new administrator account.
  • piquelctl sign-in-link: Print a one-time link that signs a browser in as the host operator.
  • piquelctl setup-link: Print the link that creates the first account.
  • piquelctl profiles: List your connection profiles and their endpoints.
  • piquelctl secrets: Manage the daemon’s encryption key for secrets.
  • piquelctl notification: Manage notification destinations and their deliveries.
  • piquelctl status: Show whether the daemon responds, its version, and the health of its subsystems.
  • piquelctl resources: Show the daemon process’s resource usage, storage, retained history, and queues, measured at most every 5 seconds (requires system:read).
  • piquelctl settings: Show the daemon’s effective host settings, read-only (requires system:read). Change them in its TOML configuration and restart it.
  • piquelctl doctor: Check this CLI’s connection and the installation’s health.
  • piquelctl dns: Inspect the daemon’s DNS providers.
  • piquelctl app: Create, inspect, edit and deploy applications.
  • piquelctl env: Create, inspect, deploy and delete an application’s environments.
  • piquelctl preview: Create, inspect, deploy and delete previews: disposable deployments of a branch.
  • piquelctl builds: Inspect Git source builds and job runs, and read their output.
  • piquelctl operation: Show an operation, waiting until it ends.
  • piquelctl analytics: Summarize deployment outcomes, retries, durations, and failure codes over a time window, for every readable application or one environment.
  • piquelctl events: Read one page of the event history, oldest first.

piquelctl login

Sign in with a passkey through your browser, and save the login.

login prints a link and a code. Open the link in any browser, even on another machine, and approve the code with your passkey. It waits until the code expires, at most 15 minutes, whatever --timeout says. It then saves the login for this daemon in ~/.config/piqueld/credentials.json (in $XDG_CONFIG_HOME when it is set), or in the file PIQUELD_CREDENTIALS_FILE names.

Grant options limit what the login may do; without them, it has all your account’s access. Here --app takes application IDs, not names, which cannot be looked up before signing in.

piquelctl login [OPTIONS]

Options:

  • --preset <PRESET>: Grant the permissions of this preset.

    • read-only: Read applications, their logs and history.
    • deploy: Read and deploy applications, such as for CI.
    • developer: Everything on applications but deleting them, including running commands in them.
    • admin: Every permission, on the selected applications or on the installation.

  • --permission <PERMISSION>: Grant this permission.

    Repeat it to grant several.

    • admin: Every ability, including permissions added later.
    • apps:read: Read configuration, status, deployments and secret names.
    • apps:write: Edit configuration, apply manifests, rename and add environments.
    • apps:deploy: Deploy and reconcile environments, create and deploy previews.
    • apps:delete: Delete applications, environments and previews.
    • previews:deploy: Create and deploy previews and read their logs.
    • previews:delete: Delete and prune previews.
    • secrets:write: Store and delete secret values.
    • logs:read: Read runtime, build and job logs.
    • apps:exec: Run commands in running containers, which can read secret values.
    • events:read: Read history, diagnostics and analytics.
    • apps:create: Create applications.
    • system:read: Read daemon configuration, resources, history and notifications.
    • system:operate: Recover the secret key and retry notifications.
    • accounts:manage: Manage accounts with equal or less access, and invitations.
    • audit:read: Read every account’s audit trail.
    • telemetry:grant: Grant environments every application’s telemetry.
    • notifications:manage: Manage notification destinations.

  • --app <APPLICATION_ID>: Limit the application permissions to this application.

    Repeat it to allow several applications. Without it, the permissions apply to every application. Installation-wide permissions, such as system:read, are never limited.

piquelctl logout

Sign out: revoke the current credential and delete its saved copy.

With PIQUELD_TOKEN set, it revokes that token and leaves saved logins alone.

piquelctl logout [OPTIONS]

piquelctl whoami

Show who you are signed in as and what the current credential may do.

piquelctl whoami [OPTIONS]

piquelctl account

Manage accounts: list, edit and delete them, change their grants and passkeys, and create and revoke invitation and enrollment links.

piquelctl account [OPTIONS] <COMMAND>

Commands:

piquelctl account list

List the accounts you can see, with their grants.

With accounts:manage, that is every account, and the host operator’s live browser sessions, which token revoke ends. Otherwise, it is only yours.

piquelctl account list [OPTIONS]

piquelctl account access

Replace an account’s grants.

Choose the new grants with --preset, --permission, or both. Needs accounts:manage, every grant the account has, and every grant you give it. An API token can’t change grants.

piquelctl account access [OPTIONS] <ACCOUNT>

Arguments:

  • <ACCOUNT>: Account username or ID.

Options:

  • --preset <PRESET>: Grant the permissions of this preset.

    • read-only: Read applications, their logs and history.
    • deploy: Read and deploy applications, such as for CI.
    • developer: Everything on applications but deleting them, including running commands in them.
    • admin: Every permission, on the selected applications or on the installation.

  • --permission <PERMISSION>: Grant this permission.

    Repeat it to grant several.

    • admin: Every ability, including permissions added later.
    • apps:read: Read configuration, status, deployments and secret names.
    • apps:write: Edit configuration, apply manifests, rename and add environments.
    • apps:deploy: Deploy and reconcile environments, create and deploy previews.
    • apps:delete: Delete applications, environments and previews.
    • previews:deploy: Create and deploy previews and read their logs.
    • previews:delete: Delete and prune previews.
    • secrets:write: Store and delete secret values.
    • logs:read: Read runtime, build and job logs.
    • apps:exec: Run commands in running containers, which can read secret values.
    • events:read: Read history, diagnostics and analytics.
    • apps:create: Create applications.
    • system:read: Read daemon configuration, resources, history and notifications.
    • system:operate: Recover the secret key and retry notifications.
    • accounts:manage: Manage accounts with equal or less access, and invitations.
    • audit:read: Read every account’s audit trail.
    • telemetry:grant: Grant environments every application’s telemetry.
    • notifications:manage: Manage notification destinations.

  • --app <NAME_OR_ID>: Limit the application permissions to this application.

    Repeat it to allow several applications. Without it, the permissions apply to every application. Installation-wide permissions, such as system:read, are never limited.

  • -y, --yes: Skip the confirmation prompt.

piquelctl account invite

Print a link that creates a new account with the selected grants.

Choose the grants with --preset, --permission, or both. The link works once within 24 hours. Needs accounts:manage and every grant it hands out. An API token can’t create invitations.

piquelctl account invite [OPTIONS]

Options:

  • --preset <PRESET>: Grant the permissions of this preset.

    • read-only: Read applications, their logs and history.
    • deploy: Read and deploy applications, such as for CI.
    • developer: Everything on applications but deleting them, including running commands in them.
    • admin: Every permission, on the selected applications or on the installation.

  • --permission <PERMISSION>: Grant this permission.

    Repeat it to grant several.

    • admin: Every ability, including permissions added later.
    • apps:read: Read configuration, status, deployments and secret names.
    • apps:write: Edit configuration, apply manifests, rename and add environments.
    • apps:deploy: Deploy and reconcile environments, create and deploy previews.
    • apps:delete: Delete applications, environments and previews.
    • previews:deploy: Create and deploy previews and read their logs.
    • previews:delete: Delete and prune previews.
    • secrets:write: Store and delete secret values.
    • logs:read: Read runtime, build and job logs.
    • apps:exec: Run commands in running containers, which can read secret values.
    • events:read: Read history, diagnostics and analytics.
    • apps:create: Create applications.
    • system:read: Read daemon configuration, resources, history and notifications.
    • system:operate: Recover the secret key and retry notifications.
    • accounts:manage: Manage accounts with equal or less access, and invitations.
    • audit:read: Read every account’s audit trail.
    • telemetry:grant: Grant environments every application’s telemetry.
    • notifications:manage: Manage notification destinations.

  • --app <NAME_OR_ID>: Limit the application permissions to this application.

    Repeat it to allow several applications. Without it, the permissions apply to every application. Installation-wide permissions, such as system:read, are never limited.

piquelctl account enroll

Print a link that adds a passkey to an existing account.

The link works once within 24 hours, and signs in whoever uses it as that account. Anyone may create one for their own account; another account needs accounts:manage and every grant it has. An API token or limited login can’t create enrollment links.

piquelctl account enroll [OPTIONS] <ACCOUNT>

Arguments:

  • <ACCOUNT>: Account username or ID.

piquelctl account update

Change an account’s username or display name.

Give --username, --display-name, or both; the other keeps its value. Anyone may change their own account; another account needs accounts:manage and every grant it has. An API token or limited login can’t change its own account. Renaming an account you saved a login for also renames the login, so --account finds it.

piquelctl account update [OPTIONS] <--username <USERNAME>|--display-name <NAME>> <ACCOUNT>

Arguments:

  • <ACCOUNT>: Account username or ID.

Options:

  • --username <USERNAME>: Rename the account to this unique username.

  • --display-name <NAME>: Set the account’s display name.

    An empty value clears it.

piquelctl account delete

Delete an account, with its passkeys, sessions and API tokens.

Anyone may delete their own account; another account needs accounts:manage and every grant it has. An API token or limited login can’t delete its own account. The daemon refuses when no account with admin and a passkey would remain.

piquelctl account delete [OPTIONS] <ACCOUNT>

Arguments:

  • <ACCOUNT>: Account username or ID.

Options:

  • -y, --yes: Skip the confirmation prompt.

piquelctl account passkey

List, rename and remove passkeys.

Add a passkey with an account enroll link.

piquelctl account passkey [OPTIONS] <COMMAND>

Commands:

piquelctl account passkey list

List the passkeys of the accounts you can see, with their owners.

With accounts:manage, that is every account. Otherwise, it is only yours.

piquelctl account passkey list [OPTIONS] [ACCOUNT]

Arguments:

  • [ACCOUNT]: Only list this account’s passkeys, by username or ID.

piquelctl account passkey rename

Rename a passkey.

Anyone may rename their own; another account’s needs accounts:manage and every grant it has. An API token or limited login can’t rename its own account’s.

piquelctl account passkey rename [OPTIONS] <ID> <NAME>

Arguments:

  • <ID>: Passkey ID, from account passkey list.
  • <NAME>: New name.

piquelctl account passkey remove

Remove a passkey, so it can no longer sign in.

Sessions it signed in stay valid until revoked with token revoke. Anyone may remove their own; another account’s needs accounts:manage and every grant it has. An API token or limited login can’t remove its own account’s. The daemon refuses when no account with admin and a passkey would remain.

piquelctl account passkey remove [OPTIONS] <ID>

Arguments:

  • <ID>: Passkey ID, from account passkey list.

Options:

  • -y, --yes: Skip the confirmation prompt.

piquelctl account invitation

List and revoke pending invitation and enrollment links.

piquelctl account invitation [OPTIONS] <COMMAND>

Commands:

piquelctl account invitation list

List pending invitation and enrollment links, with the grants they hand out.

Needs accounts:manage; without it, the list is empty.

piquelctl account invitation list [OPTIONS]

piquelctl account invitation revoke

Revoke a pending invitation or enrollment link, so it no longer works.

An invitation needs accounts:manage and every grant it hands out. An enrollment link needs what account enroll does.

piquelctl account invitation revoke [OPTIONS] <ID>

Arguments:

  • <ID>: Invitation ID, from account invitation list.

piquelctl token

Create, list and revoke your API tokens and sessions, or revoke an account’s.

piquelctl token [OPTIONS] <COMMAND>

Commands:

piquelctl token create

Create an API token for your account, and print it.

The token has only the grants you select, with --preset, --permission, or both, and you must hold them. Use it with PIQUELD_TOKEN. Keep it safe: it is printed once and never shown again. An API token can’t create tokens.

piquelctl token create [OPTIONS] <NAME>

Arguments:

  • <NAME>: Token name, up to 200 bytes.

Options:

  • --preset <PRESET>: Grant the permissions of this preset.

    • read-only: Read applications, their logs and history.
    • deploy: Read and deploy applications, such as for CI.
    • developer: Everything on applications but deleting them, including running commands in them.
    • admin: Every permission, on the selected applications or on the installation.

  • --permission <PERMISSION>: Grant this permission.

    Repeat it to grant several.

    • admin: Every ability, including permissions added later.
    • apps:read: Read configuration, status, deployments and secret names.
    • apps:write: Edit configuration, apply manifests, rename and add environments.
    • apps:deploy: Deploy and reconcile environments, create and deploy previews.
    • apps:delete: Delete applications, environments and previews.
    • previews:deploy: Create and deploy previews and read their logs.
    • previews:delete: Delete and prune previews.
    • secrets:write: Store and delete secret values.
    • logs:read: Read runtime, build and job logs.
    • apps:exec: Run commands in running containers, which can read secret values.
    • events:read: Read history, diagnostics and analytics.
    • apps:create: Create applications.
    • system:read: Read daemon configuration, resources, history and notifications.
    • system:operate: Recover the secret key and retry notifications.
    • accounts:manage: Manage accounts with equal or less access, and invitations.
    • audit:read: Read every account’s audit trail.
    • telemetry:grant: Grant environments every application’s telemetry.
    • notifications:manage: Manage notification destinations.

  • --app <NAME_OR_ID>: Limit the application permissions to this application.

    Repeat it to allow several applications. Without it, the permissions apply to every application. Installation-wide permissions, such as system:read, are never limited.

  • --days <DAYS>: Expire the token after this many days, from 1.

    The daemon refuses more days than its auth.max_token_days. Default: 90.

  • --no-expiry: Never expire the token.

    The daemon refuses it when it sets auth.max_token_days.

  • --tailnet <USER_OR_TAG>: Accept the token only over the tailnet, from this user’s devices or devices with this tag.

    Give a login name, such as [email protected], or a tag, such as tag:ci. The daemon needs its tailnet node or a private dashboard hostname.

piquelctl token list

List the sessions and API tokens of an account, with their grants and expiry.

Without --user, lists yours.

piquelctl token list [OPTIONS]

Options:

  • --user <ACCOUNT>: List this account’s instead, by username or ID.

    Accounts other than yours need accounts:manage.

piquelctl token revoke

Revoke a session or API token by ID, or every one of an account with --all.

Give the ID of a credential from token list, or of a host operator browser session, from account list.

piquelctl token revoke [OPTIONS] [ID]

Arguments:

  • [ID]: Credential ID.

Options:

  • --all: Revoke every session and API token of an account instead.

    Without --user, revokes yours, including the login this command uses. An API token or limited login can’t revoke its own account’s.

  • --user <ACCOUNT>: Revoke this account’s with --all, by username or ID.

    Accounts other than yours need accounts:manage and every grant the account has.

  • -y, --yes: Skip the confirmation prompt of --all.

piquelctl audit

Read the audit trail of API requests, newest first.

Each line is one request: when it was made, its outcome and status, what it did and to which application or environment, who made it with which credential, and from where. With audit:read, you see every account’s requests. Without it, you see only your own account’s, and an API token only its own.

piquelctl audit [OPTIONS]
       piquelctl audit <COMMAND>

Options:

  • --user <ACCOUNT>: Only show the requests of this account, by username or ID, even a deleted one.

    Accounts other than yours need audit:read. Unlike the global --account, it doesn’t choose the login you read with.

  • --credential <CREDENTIAL>: Only show the requests made with this credential ID, from token list.

  • --outcome <OUTCOME>: Only show the requests with this outcome.

    • allowed: Authorized, and succeeded.
    • denied: Refused: missing credentials or permission, or a target hidden from the caller.
    • failed: Authorized, but failed.

  • --cursor <CURSOR>: Read the page after this cursor, which the previous page printed.

  • --limit <LIMIT>: Show at most this many items, from 1 to 100. Default: 50.

Commands:

piquelctl audit verify

Check that no one altered the audit trail.

It checks the trail’s hash chain, and exits with code 3 when a record was edited, inserted or removed. It prints the newest link: keep it elsewhere to also detect that the newest records were removed. Needs audit:read.

piquelctl audit verify [OPTIONS]

piquelctl recover-admin

Print a one-time link that creates a new administrator account.

Use it to regain access when no administrator can sign in. Run it on the daemon host as root or as the daemon’s user, such as with sudo: the daemon serves it only over its Unix socket. The link works once within 24 hours and replaces any earlier one. Issuing it raises a security notification.

piquelctl recover-admin [OPTIONS]

Print a one-time link that signs a browser in as the host operator.

The browser gets full access for 12 hours. The link works once within 10 minutes. Run it on the daemon host as root or as the daemon’s user: the daemon serves it only over its Unix socket, to the host operator. It never sends PIQUELD_TOKEN or a saved login. Issuing it raises a security notification.

piquelctl sign-in-link [OPTIONS]

Print the link that creates the first account.

Run it on the daemon host: the daemon serves it only over its Unix socket, and only until the first account exists.

piquelctl setup-link [OPTIONS]

Options:

  • --open: Also open the link in your default browser.

piquelctl profiles

List your connection profiles and their endpoints.

It reads the profiles files without contacting a daemon, and ignores --profile and the endpoint options.

piquelctl profiles [OPTIONS]

piquelctl secrets

Manage the daemon’s encryption key for secrets.

piquelctl secrets [OPTIONS] <COMMAND>

Commands:

piquelctl secrets recover-key

Recover from a lost secret key by discarding every value it encrypted.

Use it only when the daemon’s secrets.key is lost and you have no backup: the daemon refuses while the key still works. It discards the stored and generated secret values of ALL applications and environments and the repository webhook secrets, and deletes every notification destination, since their URLs are encrypted. Running services keep their Docker secrets. Afterwards, set the stored secrets again and deploy, which also generates new values for generated secrets, give each repository a new webhook secret with app repository webhook rotate, and add the notification destinations again with notification set. Needs system:operate.

piquelctl secrets recover-key [OPTIONS]

Options:

  • --yes: Skip the confirmation prompt.

piquelctl notification

Manage notification destinations and their deliveries.

piquelctl notification [OPTIONS] <COMMAND>

Commands:

piquelctl notification list

List notification destinations and what each receives.

Their URLs are never shown. Needs system:read or notifications:manage.

piquelctl notification list [OPTIONS]

piquelctl notification set

Create a notification destination, or change one.

Options you omit keep the current settings. A new destination needs --url-file or --url-stdin. It receives every category but deployment_succeeded, about every application, without previews. Changing its URL or kind cancels its pending deliveries. Needs notifications:manage.

piquelctl notification set [OPTIONS] <NAME>

Arguments:

  • <NAME>: Destination name.

Options:

  • --kind <KIND>: Payload format.

    A new destination defaults to json.

    • json: Versioned JSON describing the event.
    • discord: A Discord webhook message.

  • --url-file <PATH>: Read the webhook URL from this file.

  • --url-stdin: Read the webhook URL from standard input.

  • --enabled <BOOL>: Whether to send notifications.

    false pauses the destination and cancels its pending deliveries. true resumes it, without sending what happened meanwhile. Values: true, false.

  • --categories <CATEGORIES>: Receive only these categories: comma-separated, or '' for none.

    A category that stays keeps its message. Values: build_failures, deployment_failures, service_degradation, daemon_failures, recovery, security, daemon_started, deployment_succeeded.

  • --message <CATEGORY=TEXT>: Send TEXT with each notification of CATEGORY, and receive that category.

    TEXT has 1 to 1000 characters, such as a Discord role mention <@&ROLE_ID>. CATEGORY is one of the values --categories accepts. Repeat it for several categories.

  • --no-message <CATEGORY>: Stop sending text with this category’s notifications.

    Repeat it for several categories. Values: build_failures, deployment_failures, service_degradation, daemon_failures, recovery, security, daemon_started, deployment_succeeded.

  • --apps <APPS>: Receive notifications only about these applications: comma-separated names or IDs, or '' for none.

    Daemon-wide notifications, such as daemon failures and security events, arrive either way.

  • --all-apps: Receive notifications about every application, including ones created later.

  • --previews <BOOL>: Whether to receive notifications about previews. Values: true, false.

piquelctl notification test

Send a test notification to a destination now.

It fails unless the receiver acknowledges it. The test skips the delivery queue and history. Needs notifications:manage.

piquelctl notification test [OPTIONS] <NAME>

Arguments:

  • <NAME>: Destination name.

piquelctl notification delete

Delete a notification destination and cancel its pending deliveries.

The delivery history keeps its name. Needs notifications:manage.

piquelctl notification delete [OPTIONS] <NAME>

Arguments:

  • <NAME>: Destination name.

Options:

  • -y, --yes: Skip the confirmation prompt.

piquelctl notification deliveries

List notification deliveries, newest first, with their state, attempts and last error.

Needs system:read.

piquelctl notification deliveries [OPTIONS]

Options:

  • --cursor <CURSOR>: Read the page after this cursor, which the previous page printed.
  • --limit <LIMIT>: Show at most this many items, from 1 to 100. Default: 50.

piquelctl notification retry

Try a failed delivery again now, with the destination’s current settings.

Needs system:operate. The daemon refuses a delivery that hasn’t failed or that the destination no longer receives, and says why.

piquelctl notification retry [OPTIONS] <ID>

Arguments:

  • <ID>: Delivery ID, from notification deliveries.

piquelctl status

Show whether the daemon responds, its version, and the health of its subsystems.

piquelctl status [OPTIONS]

piquelctl resources

Show the daemon process’s resource usage, storage, retained history, and queues, measured at most every 5 seconds (requires system:read).

piquelctl resources [OPTIONS]

piquelctl settings

Show the daemon’s effective host settings, read-only (requires system:read). Change them in its TOML configuration and restart it.

piquelctl settings [OPTIONS]

piquelctl doctor

Check this CLI’s connection and the installation’s health.

Shows the resolved endpoint and credential, then each daemon check as pass, warn, fail, or skip with a next step. Exits 6 when a check fails.

piquelctl doctor [OPTIONS]

piquelctl dns

Inspect the daemon’s DNS providers.

piquelctl dns [OPTIONS] <COMMAND>

Commands:

piquelctl dns refresh

Check every DNS provider’s credentials and zones now.

The daemon otherwise checks them every hour. It reads credential files only when it starts, so restart it after changing one. Needs system:operate.

piquelctl dns refresh [OPTIONS]

piquelctl app

Create, inspect, edit and deploy applications.

piquelctl app [OPTIONS] <COMMAND>

Commands:

piquelctl app create

Create an empty application.

Add services, volumes and routes to it with the other app commands. Needs apps:create.

piquelctl app create [OPTIONS] <NAME>

Arguments:

  • <NAME>: Name of the new application, unused by any other.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --yes: Skip the confirmation prompt.

piquelctl app service

Add, change and remove an application’s services.

piquelctl app service [OPTIONS] <COMMAND>

Commands:

piquelctl app service add

Add a service that runs an image, or builds a Git repository with --git.

The new service runs one replica and has no other settings. Adding a service whose name is taken fails.

piquelctl app service add [OPTIONS] <APP> <SERVICE> [IMAGE]

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • [IMAGE]: Image to run, such as nginx:stable. It may reference variables. Omit it when you pass --git.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --git <URL|self>: Build this Git repository with Docker instead of running an image. It takes a clone URL, a path on the daemon’s host, or self: the manifest’s own repository, at the commit the manifest was read from.
  • --branch <BRANCH>: Branch to build when no commit is pinned. Default: main. self doesn’t take one.
  • --commit <COMMIT>: Build this full commit hash instead of the branch head. self doesn’t take one.
  • --dockerfile <PATH>: Dockerfile path, relative to the repository root. Default: Dockerfile.
  • --context <PATH>: Build context directory, relative to the repository root. Default: ..
  • --build-arg <KEY=VALUE>: Docker build argument. Repeat it to set several. Values aren’t secret: Docker records them in the image.
  • --target <STAGE>: Dockerfile stage to build. By default, Docker builds the last stage.

piquelctl app service remove

Remove a service.

Its routes, jobs and export are removed with it, and other services stop depending on it. The volumes it mounts keep their data.

piquelctl app service remove [OPTIONS] <APP> <SERVICE>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service rename

Rename a service.

Its routes, jobs, export and the services depending on it follow the new name. Applications importing it must import the new name. The next deployment replaces the running service.

piquelctl app service rename [OPTIONS] <APP> <SERVICE> <NEW_NAME>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <NEW_NAME>: New service name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service replicas

Set the number of replicas the service runs.

piquelctl app service replicas [OPTIONS] <APP> <SERVICE> <REPLICAS>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <REPLICAS>: Number of replicas, from 1 to 100, or a variable reference such as ${{ vars.web_replicas }}.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service source

Set where the service’s image comes from: a prebuilt image or a Git build.

image and git replace the source. The other commands change one setting of the current Git source.

piquelctl app service source [OPTIONS] <COMMAND>

Commands:

piquelctl app service source image

Run a prebuilt image, replacing the service’s source.

piquelctl app service source image [OPTIONS] <APP> <SERVICE> <IMAGE>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <IMAGE>: Image reference, such as nginx:stable. It may reference variables.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service source git

Build a Git repository with Docker, replacing the service’s source.

Build settings you don’t pass get their defaults.

piquelctl app service source git [OPTIONS] <APP> <SERVICE> <URL|self>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <URL|self>: Git clone URL, a path on the daemon’s host, or self: the manifest’s own repository, at the commit the manifest was read from.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --branch <BRANCH>: Branch to build when no commit is pinned. Default: main. self doesn’t take one.
  • --commit <COMMIT>: Build this full commit hash instead of the branch head. self doesn’t take one.
  • --dockerfile <PATH>: Dockerfile path, relative to the repository root. Default: Dockerfile.
  • --context <PATH>: Build context directory, relative to the repository root. Default: ..
  • --build-arg <KEY=VALUE>: Docker build argument. Repeat it to set several. Values aren’t secret: Docker records them in the image.
  • --target <STAGE>: Dockerfile stage to build. By default, Docker builds the last stage.

piquelctl app service source url

Change the repository the service builds.

piquelctl app service source url [OPTIONS] <APP> <SERVICE> <URL>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <URL>: Git clone URL, or a path on the daemon’s host.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service source branch

Change the branch the service builds.

piquelctl app service source branch [OPTIONS] <APP> <SERVICE> <BRANCH>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <BRANCH>: Branch name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service source commit

Pin the commit the service builds, or follow the branch again with --clear.

piquelctl app service source commit [OPTIONS] <APP> <SERVICE> [COMMIT]

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • [COMMIT]: Full commit hash to build.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --clear: Remove the pinned commit and build the branch head again.

piquelctl app service source dockerfile

Change the Dockerfile the service builds.

piquelctl app service source dockerfile [OPTIONS] <APP> <SERVICE> <PATH>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <PATH>: Dockerfile path, relative to the repository root.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service source context

Change the directory the service’s build uses as its context.

piquelctl app service source context [OPTIONS] <APP> <SERVICE> <PATH>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <PATH>: Build context directory, relative to the repository root.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service env

Set or remove one environment variable of a service.

piquelctl app service env [OPTIONS] <COMMAND>

Commands:

piquelctl app service env set

Set an environment variable, keeping the service’s others.

piquelctl app service env set [OPTIONS] <APP> <SERVICE> <KEY> <VALUE>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <KEY>: Variable name.
  • <VALUE>: Variable value. It may reference variables, such as ${{ vars.<name> }}.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service env remove

Remove an environment variable.

Removing one the service doesn’t set fails.

piquelctl app service env remove [OPTIONS] <APP> <SERVICE> <KEY>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <KEY>: Variable name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service command

Replace the image’s entrypoint with the elements after --.

Put the command’s options before --. Without elements, the service uses the image’s own entrypoint.

piquelctl app service command [OPTIONS] <APP> <SERVICE> [-- <COMMAND>...]

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • [COMMAND]...: Entrypoint elements, after --. Each one is passed as is, spaces included, and may reference variables.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service arguments

Replace the image’s default arguments with the elements after --.

Put the command’s options before --. Without elements, the service uses the image’s own arguments.

piquelctl app service arguments [OPTIONS] <APP> <SERVICE> [-- <ARGUMENTS>...]

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • [ARGUMENTS]...: Argument elements, after --. Each one is passed as is, spaces included, and may reference variables.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service depends-on

Set the services that must be healthy before this one rolls out.

List them after --. Without any, the service depends on none. Jobs of the service wait for them too.

piquelctl app service depends-on [OPTIONS] <APP> <SERVICE> [-- <SERVICES>...]

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • [SERVICES]...: Names of other services of the application, after --.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service rollout

Set the order and monitor window of the service’s rollouts.

A flag you omit returns to its default, so running it without flags restores both defaults.

piquelctl app service rollout [OPTIONS] <APP> <SERVICE>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --order <ORDER>: stop-first stops the old task before starting its replacement, and start-first starts the replacement first. By default, the order is stop-first when the service mounts a volume writable, else start-first.
  • --monitor-seconds <SECONDS>: Seconds Docker watches each replacement task for failure, from 1 to 3600. By default, 30.

piquelctl app service telemetry

Choose whether the service receives the daemon’s own telemetry.

With on, the service receives the traces, metrics and logs of every application on a socket mounted at /run/piqueld/telemetry, in environments granted telemetry with env telemetry. At most one service per application can receive it, and it must run one replica.

piquelctl app service telemetry [OPTIONS] <APP> <SERVICE> <on|off>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <on|off>: on to receive telemetry where the environment is granted it, off to never receive it. Values: on, off.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service mount

Mount a volume into a service, or remove a mount.

piquelctl app service mount [OPTIONS] <COMMAND>

Commands:

piquelctl app service mount set

Mount a volume at a container path, replacing any mount at that path.

piquelctl app service mount set [OPTIONS] <APP> <SERVICE> <VOLUME> <PATH>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <VOLUME>: Name of a volume the application declares, with app volume add.
  • <PATH>: Absolute container path to mount it at.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --read-only: Mount the volume read-only. A writable mount makes the service’s rollouts stop the old task first.

piquelctl app service mount remove

Remove the mount at a container path.

piquelctl app service mount remove [OPTIONS] <APP> <SERVICE> <PATH>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <PATH>: Container path of the mount.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service secret

Mount a secret into a service as a file, or remove a mount.

These commands choose where secrets appear. Set their values, and who may mount them, with app secret.

piquelctl app service secret [OPTIONS] <COMMAND>

Commands:

piquelctl app service secret list

List the secrets the application’s services mount, as saved.

piquelctl app service secret list [OPTIONS] <APP> [SERVICE]

Arguments:

  • <APP>: Application name or stable ID.
  • [SERVICE]: Service to list. Without it, every service is listed.

piquelctl app service secret add

Mount a secret as a read-only file, replacing any secret mounted at the same path.

A deployment fails while the secret has no value, or when the environment may not mount it.

piquelctl app service secret add [OPTIONS] <APP> <SERVICE> <SECRET> <TARGET>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <SECRET>: Secret name: one set with app secret, or one the manifest declares to be generated. It may reference variables, such as ${{ vars.<name> }}, so each environment can mount its own secret.
  • <TARGET>: Absolute container path of the file, under /run/secrets.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service secret remove

Remove the secret mounted at a container path.

Removing a path the service doesn’t mount a secret at fails.

piquelctl app service secret remove [OPTIONS] <APP> <SERVICE> <TARGET>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <TARGET>: Container path of the secret file, under /run/secrets.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service health

Set, change, or remove a service’s health check.

The commands that change one setting need a health check of the matching kind first.

piquelctl app service health [OPTIONS] <COMMAND>

Commands:

piquelctl app service health http

Replace the health check with an HTTP check.

The check sends a GET request to the port inside the container and passes on a 2xx or 3xx status. It needs nothing in the image.

piquelctl app service health http [OPTIONS] <APP> <SERVICE> <PORT>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <PORT>: Container port to probe, from 1 to 65535.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --path <PATH>: Request path, starting with /. Default: /health.
  • --interval <SECONDS>: Seconds between checks, from 1 to 3600. Default: 10.
  • --check-timeout <SECONDS>: Seconds before a check counts as failed, from 1 to the interval. Default: 3.
  • --start-period <SECONDS>: Seconds after the container starts during which failed checks don’t count, up to 3600. A passing check makes the container healthy at once. Default: 0.
  • --retries <RETRIES>: Consecutive failed checks that make the container unhealthy, from 1 to 100. Default: 3.

piquelctl app service health command

Replace the health check with a command, given after --.

The command runs inside the container, without a shell, and passes when it exits with status 0. Put the command’s options before --.

piquelctl app service health command [OPTIONS] <APP> <SERVICE> -- <COMMAND>...

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <COMMAND>...: Command elements, after --. Each one is passed as is, spaces included.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --interval <SECONDS>: Seconds between checks, from 1 to 3600. Default: 10.
  • --check-timeout <SECONDS>: Seconds before a check counts as failed, from 1 to the interval. Default: 3.
  • --start-period <SECONDS>: Seconds after the container starts during which failed checks don’t count, up to 3600. A passing check makes the container healthy at once. Default: 0.
  • --retries <RETRIES>: Consecutive failed checks that make the container unhealthy, from 1 to 100. Default: 3.

piquelctl app service health clear

Remove the health check.

piquelctl app service health clear [OPTIONS] <APP> <SERVICE>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service health port

Change the port of an HTTP health check.

piquelctl app service health port [OPTIONS] <APP> <SERVICE> <PORT>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <PORT>: Container port, from 1 to 65535.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service health path

Change the request path of an HTTP health check.

piquelctl app service health path [OPTIONS] <APP> <SERVICE> <PATH>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <PATH>: Request path, starting with /.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service health command-elements

Change the command of a command health check, given after --.

piquelctl app service health command-elements [OPTIONS] <APP> <SERVICE> [-- <COMMAND>...]

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • [COMMAND]...: Command elements, after --.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service health interval

Change the seconds between health checks.

piquelctl app service health interval [OPTIONS] <APP> <SERVICE> <SECONDS>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <SECONDS>: Seconds between checks, from 1 to 3600.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service health timeout

Change the seconds before a health check counts as failed.

piquelctl app service health timeout [OPTIONS] <APP> <SERVICE> <SECONDS>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <SECONDS>: Seconds before a check counts as failed, from 1 to the interval.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service health start-period

Change the seconds after the container starts during which failed checks don’t count.

piquelctl app service health start-period [OPTIONS] <APP> <SERVICE> <SECONDS>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <SECONDS>: Seconds after the container starts, up to 3600.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service health retries

Change how many consecutive failed checks make the container unhealthy.

piquelctl app service health retries [OPTIONS] <APP> <SERVICE> <RETRIES>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <RETRIES>: Consecutive failed checks, from 1 to 100.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app service cpu

Set the service’s CPU limit, or remove it with --clear.

piquelctl app service cpu [OPTIONS] <APP> <SERVICE> [MILLICORES]

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • [MILLICORES]: CPU limit in millicores, from 1 to 1048576, where 1000 is one CPU.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --clear: Remove the CPU limit.

piquelctl app service memory

Set the service’s memory limit, or remove it with --clear.

piquelctl app service memory [OPTIONS] <APP> <SERVICE> [BYTES]

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • [BYTES]: Memory limit in bytes, such as 268435456 for 256 MiB.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --clear: Remove the memory limit.

piquelctl app file

List, add and remove the read-only files services mount.

piquelctl app file [OPTIONS] <COMMAND>

Commands:

piquelctl app file list

List the files the application’s services mount, as saved.

piquelctl app file list [OPTIONS] <APP> [SERVICE]

Arguments:

  • <APP>: Application name or stable ID.
  • [SERVICE]: Service to list. Without it, every service is listed.

piquelctl app file add

Mount a read-only file into a service, replacing any file at the same path.

Give its content with exactly one of --content, --from or --path. A file holds at most 500 KiB and can’t be empty.

piquelctl app file add [OPTIONS] <--content <TEXT>|--from <LOCAL_FILE>|--path <REPOSITORY_PATH>> <APP> <SERVICE> <TARGET>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <TARGET>: Absolute container path of the file.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --content <TEXT>: The file’s content. Variables in it are never rendered.
  • --from <LOCAL_FILE>: Read the content from this local file now, and save it in the manifest.
  • --path <REPOSITORY_PATH>: Read the content from this file in the manifest’s repository, relative to its root, each time a deployment fetches the manifest. Only repository-backed applications can use it.
  • --mode <MODE>: Octal permissions of the file, from 0000 to 0777, such as 0440. Root owns the file. Default: 0444.

piquelctl app file remove

Remove the file at a container path.

piquelctl app file remove [OPTIONS] <APP> <SERVICE> <TARGET>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service name.
  • <TARGET>: Container path of the file.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app volume

Declare and remove named volumes.

piquelctl app volume [OPTIONS] <COMMAND>

Commands:

piquelctl app volume add

Declare a named volume that services can mount.

Each environment and preview gets its own Docker volume when it next deploys.

piquelctl app volume add [OPTIONS] <APP> <VOLUME>

Arguments:

  • <APP>: Application name or stable ID.
  • <VOLUME>: Volume name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app volume remove

Remove a volume declaration.

Remove the volume’s mounts first. Docker keeps the volume and its data.

piquelctl app volume remove [OPTIONS] <APP> <VOLUME>

Arguments:

  • <APP>: Application name or stable ID.
  • <VOLUME>: Volume name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app route

Add, change and remove HTTPS routes and redirects.

piquelctl app route [OPTIONS] <COMMAND>

Commands:

piquelctl app route list

List the application’s deployed routes in every environment.

Each route shows its visibility, its state, and the DNS records its hostname needs.

piquelctl app route list [OPTIONS] <APP>

Arguments:

  • <APP>: Application name or stable ID.

piquelctl app route add

Add an HTTPS route to a service.

piquelctl app route add [OPTIONS] <APP> <HOSTNAME> <SERVICE> <PORT>

Arguments:

  • <APP>: Application name or stable ID.
  • <HOSTNAME>: Hostname of the route: an exact name, or a wildcard such as *.example.com. It may reference variables, such as ${{ vars.domain }}.
  • <SERVICE>: Service that serves the route.
  • <PORT>: HTTP port the service listens on inside its container.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --visibility <VISIBILITY>: public serves everyone, private only devices on the tailnet. The environment’s visibility ceiling can make it stricter. Default: private. Values: public, private.
  • --name <NAME>: Stable route name, unique within the application. It selects the route in every environment and preview, such as with env url --route.

piquelctl app route redirect

Add an HTTPS route that the gateway answers with a redirect.

piquelctl app route redirect [OPTIONS] <APP> <HOSTNAME> <URL>

Arguments:

  • <APP>: Application name or stable ID.
  • <HOSTNAME>: Hostname of the route: an exact name, or a wildcard such as *.example.com. It may reference variables, such as ${{ vars.domain }}.
  • <URL>: Destination: an absolute http or https URL, without query or fragment. It may reference variables.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --status <STATUS>: HTTP status of the redirect: 301, 302, 303, 307 or 308. Default: 308.
  • --no-preserve-path: Drop the request path and query instead of appending them to the destination.
  • --visibility <VISIBILITY>: public serves everyone, private only devices on the tailnet. The environment’s visibility ceiling can make it stricter. Default: private. Values: public, private.
  • --name <NAME>: Stable route name, unique within the application. It selects the route in every environment and preview, such as with env url --route.

piquelctl app route visibility

Change who can connect to a route.

The next deployment withdraws the route from its old listener as it starts.

piquelctl app route visibility [OPTIONS] <APP> <HOSTNAME> <VISIBILITY>

Arguments:

  • <APP>: Application name or stable ID.
  • <HOSTNAME>: Hostname of the route: an exact name, or a wildcard such as *.example.com. It may reference variables, such as ${{ vars.domain }}.
  • <VISIBILITY>: public serves everyone, private only devices on the tailnet. Values: public, private.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app route name

Name a route, or remove its name.

A name selects the same route in every environment and preview, such as with env url --route NAME.

piquelctl app route name [OPTIONS] <APP> <HOSTNAME> [NAME]

Arguments:

  • <APP>: Application name or stable ID.
  • <HOSTNAME>: Hostname of the route: an exact name, or a wildcard such as *.example.com. It may reference variables, such as ${{ vars.domain }}.
  • [NAME]: New route name, unique within the application. Omit it to remove the name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app route remove

Remove a route.

piquelctl app route remove [OPTIONS] <APP> <HOSTNAME>

Arguments:

  • <APP>: Application name or stable ID.
  • <HOSTNAME>: Hostname of the route: an exact name, or a wildcard such as *.example.com. It may reference variables, such as ${{ vars.domain }}.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app job

Add, reorder and remove the jobs that run before each rollout.

piquelctl app job [OPTIONS] <COMMAND>

Commands:

piquelctl app job set

Add a job that runs before each rollout, or replace the job with this name.

A new job runs after the existing ones, and a replaced job keeps its position. Jobs run in order, after their service’s dependencies are healthy, and the other services wait until every job succeeds.

piquelctl app job set [OPTIONS] <APP> <JOB> <SERVICE> -- <COMMAND>...

Arguments:

  • <APP>: Application name or stable ID.
  • <JOB>: Job name.
  • <SERVICE>: Service whose image, environment, secrets, mounts and startup dependencies the job reuses.
  • <COMMAND>...: Command the job runs, after --. It replaces the service’s command and arguments.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --timeout-seconds <SECONDS>: Seconds the job may run before it fails the deployment, from 1 to 86400. By default, the job’s current timeout, or 300 for a new job.
  • --volume-access <ACCESS>: How the job mounts its service’s volumes. By default, the job’s current access, or read-only for a new job.
    • read-only: Mount every volume read-only, so the job runs beside the services.
    • exclusive: Keep writable volumes writable, and stop every service that mounts one until the rollout.
  • --stop-service <on|off>: on to stop the job’s service before the job runs, once its startup dependencies are ready, until the rollout; off to run it beside the service. By default, the job’s current setting, or off for a new job. Values: on, off.
  • --env <KEY=VALUE>: Environment variable for the job only, added to its service’s. Repeat it to set several. They replace the job’s own variables, which it keeps when you pass none.
  • --clear-env: Remove the job’s own environment variables.
  • --secret <NAME=TARGET>: Secret for the job only, in addition to its service’s, mounted at TARGET, an absolute path under /run/secrets/ such as /run/secrets/db. Repeat it to mount several. They replace the job’s own secrets, which it keeps when you pass none.
  • --clear-secrets: Remove the job’s own secrets.

piquelctl app job move

Move a job to another position in the run order.

piquelctl app job move [OPTIONS] <APP> <JOB> <POSITION>

Arguments:

  • <APP>: Application name or stable ID.
  • <JOB>: Job name.
  • <POSITION>: New 1-based position in the run order. A position past the end moves the job last.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app job remove

Remove a job.

piquelctl app job remove [OPTIONS] <APP> <JOB>

Arguments:

  • <APP>: Application name or stable ID.
  • <JOB>: Job name.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app export

Let other applications reach this application’s services privately.

piquelctl app export [OPTIONS] <COMMAND>

Commands:

piquelctl app export list

List the services the application exports, as saved.

piquelctl app export list [OPTIONS] <APP>

Arguments:

  • <APP>: Application name or stable ID.

piquelctl app export set

Export a service to other applications, or replace who may import it.

Their services reach it as <service>.<application> once both sides have deployed the link.

piquelctl app export set [OPTIONS] --applications <APPS> <APP> <SERVICE>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service of the application to export.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --applications <APPS>: Applications whose environments may import the service. Separate several with commas, or repeat the option. Required.
  • --previews: Let previews of those applications import it too. Without it, previews can’t, even if they could before.

piquelctl app export remove

Stop exporting a service.

piquelctl app export remove [OPTIONS] <APP> <SERVICE>

Arguments:

  • <APP>: Application name or stable ID.
  • <SERVICE>: Service of the application to export.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app import

Reach the services other applications export, as <service>.<application>.

piquelctl app import [OPTIONS] <COMMAND>

Commands:

piquelctl app import list

List the services the application imports, as saved.

env show reports whether each one connects.

piquelctl app import list [OPTIONS] <APP>

Arguments:

  • <APP>: Application name or stable ID.

piquelctl app import add

Import another application’s exported service, or change the environment it reaches.

The application’s services reach it as <service>.<application> once both sides have deployed the link.

piquelctl app import add [OPTIONS] <APP> <APPLICATION> <SERVICE>

Arguments:

  • <APP>: Application name or stable ID.
  • <APPLICATION>: Application that exports the service.
  • <SERVICE>: Exported service of that application.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --environment <ENV>: Environment of the exporting application to reach, such as staging or ${{ vars.auth_env }}. By default, the one named like the importing environment.

piquelctl app import remove

Stop importing a service.

piquelctl app import remove [OPTIONS] <APP> <APPLICATION> <SERVICE>

Arguments:

  • <APP>: Application name or stable ID.
  • <APPLICATION>: Application that exports the service.
  • <SERVICE>: Exported service of that application.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app variable

Set and remove manifest variables, and their values per environment and for previews.

piquelctl app variable [OPTIONS] <COMMAND>

Commands:

piquelctl app variable set

Set a variable’s default value, or its value in one environment or in previews.

An environment’s or the previews’ value overrides the default.

piquelctl app variable set [OPTIONS] <APP> <NAME> <VALUE>

Arguments:

  • <APP>: Application name or stable ID.
  • <NAME>: Variable name, referenced as ${{ vars.<name> }}.
  • <VALUE>: true, false and integers keep their type, and anything else is text. Text may reference system variables, such as ${{ env.name }}. Text in double quotes stays text, without the quotes.

Options:

  • --env <ENV>: Change the variable’s value in this environment instead of its default. The environment must exist.
  • --previews: Change the variable’s value in every preview, [spec.previews.variables], instead of its default.
  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --string: Keep the value as text even when it looks like a boolean or an integer.

piquelctl app variable unset

Remove a variable’s default value, or its value in one environment or in previews.

Removing a value that isn’t set fails.

piquelctl app variable unset [OPTIONS] <APP> <NAME>

Arguments:

  • <APP>: Application name or stable ID.
  • <NAME>: Variable name, referenced as ${{ vars.<name> }}.

Options:

  • --env <ENV>: Change the variable’s value in this environment instead of its default. The environment must exist.
  • --previews: Change the variable’s value in every preview, [spec.previews.variables], instead of its default.
  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app repository

Connect the application to a manifest in Git, and manage that connection.

piquelctl app repository [OPTIONS] <COMMAND>

Commands:

piquelctl app repository connect

Connect the application to a manifest file in a Git repository.

Deployments then fetch the manifest from the repository. Every environment follows --branch, as do environments created later without their own, unless the manifest declares the environment’s branch. Change an environment’s branch with env branch. You can still edit the application: deployments of the connection’s branch deploy your edits until a push changes the manifest file.

piquelctl app repository connect [OPTIONS] <APP> <URL> <PATH>

Arguments:

  • <APP>: Application name or stable ID.
  • <URL>: Git clone URL, or a path on the daemon’s host.
  • <PATH>: Path of the manifest file, relative to the repository root.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --branch <BRANCH>: Branch the environments follow. Default: main.
  • --commit <COMMIT>: Pin this full commit hash instead of following the branch.
  • --sync <MODE>: Whether to deploy pushes, as app repository sync sets it. Default: off.
    • off: Deploy only when asked.
    • poll: List the branches every --interval seconds.
    • webhook: List the branches when GitHub reports a push (see app repository webhook).
  • --interval <SECONDS>: Seconds between polls with --sync poll, from 60 to 86400. By default, 300.

piquelctl app repository disconnect

Stop reading the manifest from Git, keeping the saved manifest.

Edits are kept, and environments that followed a branch deploy the saved manifest. Declared environments lose their branch, commit and sync. It fails while services mount files from the repository: give them inline content first.

piquelctl app repository disconnect [OPTIONS] <APP>

Arguments:

  • <APP>: Application name or stable ID.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app repository url

Change the repository every environment fetches the manifest from.

piquelctl app repository url [OPTIONS] <APP> <URL>

Arguments:

  • <APP>: Application name or stable ID.
  • <URL>: Git clone URL, or a path on the daemon’s host.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app repository path

Change the manifest file every environment reads.

piquelctl app repository path [OPTIONS] <APP> <PATH>

Arguments:

  • <APP>: Application name or stable ID.
  • <PATH>: Path of the manifest file, relative to the repository root.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app repository sync

Choose whether environments and previews deploy pushes.

While sync is on, every preview, and every environment that opted in with env sync and follows an unpinned branch, redeploys when its branch moves past the head of its last deployment.

piquelctl app repository sync [OPTIONS] <APP> <MODE>

Arguments:

  • <APP>: Application name or stable ID.
  • <MODE>: How to detect pushes.
    • off: Deploy only when asked.
    • poll: List the branches every --interval seconds.
    • webhook: List the branches when GitHub reports a push (see app repository webhook).

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --interval <SECONDS>: Seconds between polls with poll, from 60 to 86400. By default, 300.

piquelctl app repository reset

Discard the edits made since the manifest was last read from the repository, saving that manifest again.

app show lists the edits. Deployments of the connection’s branch then deploy the manifest as read, until a push changes it.

piquelctl app repository reset [OPTIONS] <APP>

Arguments:

  • <APP>: Application name or stable ID.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app repository webhook

Show the GitHub webhook that reports pushes, or generate its secret.

piquelctl app repository webhook [OPTIONS] <COMMAND>

Commands:

piquelctl app repository webhook show

Show the payload URL to configure in GitHub, and when the secret was generated.

The URL appears once the daemon sets ingress.webhook_hostname.

piquelctl app repository webhook show [OPTIONS] <APP>

Arguments:

  • <APP>: Application name or stable ID.

piquelctl app repository webhook rotate

Generate a new webhook secret, replacing the previous one, and print it.

The previous secret stops working at once. The new one is shown only this time.

piquelctl app repository webhook rotate [OPTIONS] <APP>

Arguments:

  • <APP>: Application name or stable ID.

Options:

  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app list

List applications with their environments and status.

piquelctl app list [OPTIONS]

piquelctl app show

Show an application and its environments.

piquelctl app show [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

piquelctl app logs

Show recent Docker logs of the application’s only environment.

With several environments, use env logs. Needs logs:read.

piquelctl app logs [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

Options:

  • --service <SERVICE>: Only show this service’s output.

    Defaults to every service.

  • --tail <TAIL>: Show at most this many of the most recent lines, from 1 to 1000, merged across services. Default: 200.

  • --since-seconds <SECONDS>: Only show output written within this many seconds, from 1 to 86400 (a day). Default: 3600.

piquelctl app exec

Run a one-off command in a running task of a service.

The command shares the task’s image, environment, secrets, mounts and networks. Its output streams to your terminal, and piquelctl exits with its exit code. Stopping piquelctl early closes the stream, but the command may keep running. --timeout limits connecting, not the session. Needs apps:exec.

piquelctl app exec [OPTIONS] <NAME_OR_ID> <SERVICE> -- <COMMAND>...

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.
  • <SERVICE>: Service that runs the command, in one of its running tasks.
  • <COMMAND>...: Program to run and its arguments, after --.

Options:

  • --env <ENV>: Environment name or stable ID.

    Optional when the application has only one.

  • -i, --interactive: Forward standard input to the command.

  • -t, --tty: Allocate a terminal, for interactive programs such as a shell.

    It implies --interactive, and needs a terminal on standard input, which it switches to raw mode so that keys such as Ctrl-C reach the command.

piquelctl app generated-secret

Declare the secrets piqueld generates for each environment.

These commands edit spec.secrets. Changing or removing a declaration keeps values already generated; replace one with env secret regenerate.

piquelctl app generated-secret [OPTIONS] <COMMAND>

Commands:

piquelctl app generated-secret list

List the secrets the application declares for piqueld to generate, as saved.

env secret list shows the values generated in each environment.

piquelctl app generated-secret list [OPTIONS] <APP>

Arguments:

  • <APP>: Application name or stable ID.

piquelctl app generated-secret set

Declare a secret piqueld generates, or replace how it is generated.

Give exactly one of --bytes or --rsa-bits. Values already generated are kept; env secret regenerate replaces them.

piquelctl app generated-secret set [OPTIONS] <--bytes <BYTES>|--rsa-bits <RSA_BITS>> <APP> <NAME>

Arguments:

  • <APP>: Application name or stable ID.
  • <NAME>: Secret name, as services and jobs mount it.

Options:

  • --deploy: Also deploy the saved configuration.

  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.

  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.

  • --force: Save even if the application changed since the command read it. It still asks for confirmation.

  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

  • --bytes <BYTES>: Generate this many random bytes (16–512), encoded as text.

  • --encoding <ENCODING>: Text encoding of the random bytes.

    By default, hex.

    • hex: Lowercase hexadecimal, two characters per byte.
    • base64url: URL-safe base64 without padding.

  • --rsa-bits <RSA_BITS>: Generate an RSA private key of this many bits (2048, 3072, or 4096) in PKCS#8 PEM.

piquelctl app generated-secret remove

Remove a declaration.

Values already generated are kept. Removing a name the application doesn’t declare fails.

piquelctl app generated-secret remove [OPTIONS] <APP> <NAME>

Arguments:

  • <APP>: Application name or stable ID.
  • <NAME>: Secret name, as services and jobs mount it.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app secret

Manage the application’s stored secrets and who may mount them.

Values are write-only: no command prints them back.

piquelctl app secret [OPTIONS] <APPLICATION> <COMMAND>

Arguments:

  • <APPLICATION>: Application name or stable ID.

Commands:

piquelctl app secret list

List the application’s stored secrets and who may mount them.

It shows each secret’s version, never its value.

piquelctl app secret <APPLICATION> list [OPTIONS]

piquelctl app secret set

Create or replace a stored secret.

The value, of 1 to 512000 bytes, comes from a file or standard input, never from an argument. Running services keep their value until the next deployment. A new secret may be mounted by every environment and no preview, unless you set its access. Needs secrets:write.

piquelctl app secret <APPLICATION> set [OPTIONS] <NAME>

Arguments:

  • <NAME>: Secret name.

Options:

  • --file <PATH>: Read the value from this file.

  • --stdin: Read the value from standard input, dropping one trailing newline. A terminal asks for it without echo.

  • --environments <ENVIRONMENTS>: Let only these environments mount the secret: comma-separated names or IDs, or '' for none.

  • --all-environments: Let every environment mount the secret, including ones created later.

    It never includes previews.

  • --previews: Let previews mount the secret.

  • --no-previews: Stop previews from mounting the secret.

  • --expected-generation <GENERATION>: Fail unless the secret is at this generation; 0 requires that it doesn’t exist.

    Defaults to the generation it inspects, or 0 for a new secret.

  • -y, --yes: Skip the confirmation prompt.

piquelctl app secret access

Change which environments, and whether previews, may mount a stored secret.

Options you omit keep the current access. Deployments that mount a secret they may no longer use fail with secret_access_denied; running ones keep their value. Needs secrets:write.

piquelctl app secret <APPLICATION> access [OPTIONS] <NAME>

Arguments:

  • <NAME>: Secret name.

Options:

  • --environments <ENVIRONMENTS>: Let only these environments mount the secret: comma-separated names or IDs, or '' for none.

  • --all-environments: Let every environment mount the secret, including ones created later.

    It never includes previews.

  • --previews: Let previews mount the secret.

  • --no-previews: Stop previews from mounting the secret.

piquelctl app secret delete

Delete a stored secret and the Docker secrets made from it.

It fails while any environment’s configuration or deployment still uses the secret. Needs secrets:write.

piquelctl app secret <APPLICATION> delete [OPTIONS] <NAME>

Arguments:

  • <NAME>: Secret name.

Options:

  • --expected-generation <GENERATION>: Fail unless the secret is at this generation.

    Defaults to the generation it inspects.

  • -y, --yes: Skip the confirmation prompt.

piquelctl app validate

Check a TOML manifest locally, without contacting a daemon.

piquelctl app validate [OPTIONS] --file <PATH>

Options:

  • --file <PATH>: Manifest file: UTF-8 TOML of at most 2 MiB. Required.

piquelctl app plan

Show what saving a TOML manifest would change, without saving it.

It exits with code 3 when the plan is blocked.

piquelctl app plan [OPTIONS] --file <PATH>

Options:

  • --file <PATH>: Manifest file: UTF-8 TOML of at most 2 MiB. Required.

  • --expected-generation <GENERATION>: Fail unless the application is at this generation; 0 requires that it doesn’t exist.

  • --env <ENV>: Render the manifest for this environment, and compare it with that environment’s deployment.

    Defaults to the application’s only environment. With several, the plan compares the manifest as written.

piquelctl app apply

Save a TOML manifest, creating or replacing the application it names.

Without --deploy, it only saves the manifest. With it, it also deploys every environment that builds, and waits for each deployment.

piquelctl app apply [OPTIONS] --file <PATH>

Options:

  • --deploy: Also deploy the saved configuration.

  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.

  • --file <PATH>: Manifest file: UTF-8 TOML of at most 2 MiB. Required.

  • --expected-generation <GENERATION>: Fail unless the application is at this generation; 0 requires that it doesn’t exist.

    Defaults to the generation it inspects, or 0 when no application has the manifest’s name.

  • --yes: Skip the confirmation prompt.

  • --force: Replace whichever application has the manifest’s name now, or create it.

    It skips the generation and identity checks, but still asks for confirmation.

piquelctl app delete

Delete an application with all its environments and previews.

The environments’ named volumes are kept; the previews’ volumes are deleted. Needs apps:delete.

piquelctl app delete [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

Options:

  • --environments <NAMES>: Names of all the application’s environments, comma-separated.

    Required when it has several, to confirm that you delete them all.

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Defaults to the generation it inspects.

  • --yes: Skip the confirmation prompt.

  • --force: Skip the generation check.

    It still asks for confirmation.

  • --no-wait: Return once the daemon accepts the deletion, without waiting for it to end.

piquelctl app reconcile

Retry the latest operation of the application’s only environment.

It runs the operation again with its saved inputs, without fetching the manifest or resolving sources again. If the operation is still in progress, it waits for it instead. With several environments, use env reconcile. A stopped environment starts. Needs apps:deploy.

piquelctl app reconcile [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

piquelctl app stop

Stop the application’s only environment.

Its routes are withdrawn and its services scale to zero, until it is started, reconciled or deployed again. With several environments, use env stop. Needs apps:deploy.

piquelctl app stop [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

piquelctl app start

Start the application’s only environment again.

Like app reconcile, it retries the latest operation with its saved inputs. With several environments, use env start. Needs apps:deploy.

piquelctl app start [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

piquelctl app deploy

Deploy the application’s only environment.

It fetches the manifest again, from the environment’s branch for a repository-backed application, and resolves images and Git sources again. With several environments, use env deploy. Needs apps:deploy.

piquelctl app deploy [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

  • --branch <BRANCH>: Fetch the repository manifest from this branch, for this deployment only.

    The environment keeps following its own branch.

  • --commit <SHA>: Fetch the repository manifest at this full commit hash, for this deployment only.

piquelctl app rename

Rename an application.

It fails while an operation of the application is running, and for repository-backed applications, whose manifests set their name. Update metadata.name in your manifest files afterwards.

piquelctl app rename [OPTIONS] <NAME_OR_ID> <NEW_NAME>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.
  • <NEW_NAME>: New name of the application, unused by any other.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl app manifest

Print the saved manifest as TOML.

piquelctl app manifest [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

piquelctl app releases

List the application’s releases, newest first.

A release records what a deployment prepared: the manifest, and each service’s image and where it came from.

piquelctl app releases [OPTIONS] <NAME_OR_ID>

Arguments:

  • <NAME_OR_ID>: Application name or stable ID.

Options:

  • --cursor <CURSOR>: Read the page after this cursor, which the previous page printed.

piquelctl env

Create, inspect, deploy and delete an application’s environments.

piquelctl env [OPTIONS] <COMMAND>

Commands:

piquelctl env list

List an application’s environments and their status.

Previews are not listed; use preview list for them.

piquelctl env list [OPTIONS] <APPLICATION>

Arguments:

  • <APPLICATION>: Application name or stable ID.

piquelctl env create

Add an environment to an application.

Nothing is deployed until you run env deploy, or env promote for a promoted environment. The environment deploys the application’s saved manifest or, when the application is repository-backed, the manifest on its own branch.

You can’t create an environment that the saved manifest has a [spec.environments.<name>] block for: saving the manifest creates it.

piquelctl env create [OPTIONS] <APPLICATION> <NAME>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <NAME>: Name of the new environment, unique within the application: 1 to 63 lowercase letters, digits, or hyphens, starting with a letter and ending with a letter or digit.

Options:

  • --branch <BRANCH>: Branch of the manifest repository the environment follows. By default, the branch spec.manifest names. Only for repository-backed applications.
  • --commit <SHA>: Deploy this commit of --branch instead of the branch’s head: a full commit hash of 40 or 64 lowercase hexadecimal characters.
  • --promote-from <ENV>: Make the environment promoted: it never builds, and only receives releases promoted from this environment of the application, given by name or stable ID, with env promote.
  • --expected-generation <GENERATION>: Change the environment only if the application’s generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the command.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --force: Change the environment even if the application changed since the command read it. It still asks for confirmation.

piquelctl env source

Make an environment receive releases promoted from another one, or build its own source again.

Nothing is deployed. A promoted environment never builds: it deploys what env promote sends it. When the saved manifest sets the environment’s promote_from, branch, commit or sync, change it there instead.

piquelctl env source [OPTIONS] <APPLICATION> <ENVIRONMENT>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.

Options:

  • --promote-from <ENV>: Receive releases promoted from this environment of the application, given by name or stable ID.
  • --tracking: Stop receiving promoted releases and build again: the saved manifest, or the branch spec.manifest names. Use env branch afterwards to follow another branch.
  • --expected-generation <GENERATION>: Change the environment only if the application’s generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the command.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --force: Change the environment even if the application changed since the command read it. It still asks for confirmation.

piquelctl env promote

Deploy a release into a promoted environment without building it.

By default, it deploys the release of the source environment’s current deployment, which must have succeeded and be healthy now. The command asks for confirmation and waits for the deployment.

piquelctl env promote [OPTIONS] <APPLICATION> <ENVIRONMENT>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Name or stable ID of the promoted environment to deploy.

Options:

  • --deployment <ID>: Promote the release of this deployment of the source environment. The command fails if it is no longer the source’s current deployment.

  • --release <ID>: Deploy this earlier release of the application instead, with the environment’s current secrets.

  • --plan: Show what would be deployed, and any secret it can’t use, without deploying. The command exits with code 3 if the promotion would be refused. With --release, you can plan for any environment, promoted or not.

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

piquelctl env branch

Point an environment at another branch of the manifest repository, or pin or unpin its commit.

Only for repository-backed applications. Nothing is deployed: the environment’s next deployment fetches the manifest from the new branch or commit. A promoted environment has no branch; use env source --tracking first. When the saved manifest sets the environment’s branch, commit, promote_from or sync, change it there instead.

piquelctl env branch [OPTIONS] <APPLICATION> <ENVIRONMENT> <BRANCH>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.
  • <BRANCH>: Branch of the manifest repository the environment follows.

Options:

  • --commit <SHA>: Deploy this commit of the branch instead of the branch’s head: a full commit hash of 40 or 64 lowercase hexadecimal characters. Without it, the environment follows the branch’s head, unpinning any commit.
  • --expected-generation <GENERATION>: Change the environment only if the application’s generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the command.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --force: Change the environment even if the application changed since the command read it. It still asks for confirmation.

piquelctl env sync

Choose whether pushes to an environment’s branch deploy it.

This applies while the application’s repository syncs (app repository sync). An environment that opts in deploys again whenever its branch moves past the head of its last deployment; one never deployed starts following from its first deployment. A pinned commit never follows pushes. When the saved manifest sets the environment’s sync, branch, commit or promote_from, change it there instead. Opting in while the repository syncs needs the apps:deploy permission too.

piquelctl env sync [OPTIONS] <APPLICATION> <ENVIRONMENT> <on|off>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.
  • <on|off>: on deploys the environment when its branch moves; off deploys it only when you ask. Values: on, off.

piquelctl env telemetry

Grant an environment the daemon’s telemetry, or revoke it.

The receiving service of a granted environment, marked with app service telemetry, gets the traces, metrics and logs of every application. Revoking stops the export at once. Either way, the daemon mounts or unmounts the telemetry socket within seconds, which restarts the service; nothing is deployed. Both need the telemetry:grant permission. Previews are never granted.

piquelctl env telemetry [OPTIONS] <APPLICATION> <ENVIRONMENT> <on|off>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.
  • <on|off>: on grants the environment every application’s telemetry; off revokes it. Values: on, off.

piquelctl env show

Show one environment, the manifest it deploys, and its status.

piquelctl env show [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

piquelctl env visibility

Cap the visibility of an environment’s routes in the saved manifest.

Each route gets the stricter of its own visibility and this cap. The cap is saved in the environment’s [spec.environments.<name>] block. private adds the block when the manifest has none for the environment; public, which is no cap, only changes an existing one.

piquelctl env visibility [OPTIONS] <APPLICATION> <ENVIRONMENT> <VISIBILITY>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.
  • <VISIBILITY>: The strictest visibility the environment’s routes get. private keeps every route on the tailnet; public, the default, restricts nothing. Values: public, private.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl env rollback

Choose what happens when an environment’s rollout fails.

A rollout fails when Docker pauses a service update because a new container failed within its monitor window. With automatic, piqueld then restores the environment’s last successful deployment, like env restore; with manual, the environment stays degraded until you deploy or restore. default is automatic for promoted environments and manual for the others. The setting is saved in the environment’s [spec.environments.<name>] block. Data is never reverted.

piquelctl env rollback [OPTIONS] <APPLICATION> <ENVIRONMENT> <ROLLBACK>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.
  • <ROLLBACK>: What happens when a rollout fails.
    • automatic: Restore the last successful deployment.
    • manual: Stay degraded until someone acts.
    • default: Automatic for promoted environments, manual otherwise.

Options:

  • --deploy: Also deploy the saved configuration.
  • --no-wait: Return once the change is saved, or its deployment accepted, without waiting for the deployment to end.
  • --expected-generation <GENERATION>: Save only if the application’s saved generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the save instead of being overwritten.
  • --force: Save even if the application changed since the command read it. It still asks for confirmation.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.

piquelctl env rename

Rename an environment without redeploying it.

The command fails while the manifest the environment deploys, or the application’s saved manifest, has a [spec.environments.<name>] block for the old or the new name.

piquelctl env rename [OPTIONS] <APPLICATION> <ENVIRONMENT> <NEW_NAME>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.
  • <NEW_NAME>: New environment name, unique within the application: 1 to 63 lowercase letters, digits, or hyphens, starting with a letter and ending with a letter or digit.

Options:

  • --expected-generation <GENERATION>: Change the environment only if the application’s generation is still GENERATION. By default, it must still be the generation the command read, so a concurrent change fails the command.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --force: Change the environment even if the application changed since the command read it. It still asks for confirmation.

piquelctl env delete

Delete an environment, keeping its named volumes.

The command removes the environment’s services and network, after confirmation, and waits until it is gone. To delete an environment that the saved manifest declares, remove its [spec.environments.<name>] block first.

piquelctl env delete [OPTIONS] <APPLICATION> <ENVIRONMENT>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Defaults to the generation it inspects.

  • --yes: Skip the confirmation prompt.

  • --force: Skip the generation check.

    It still asks for confirmation.

  • --no-wait: Return once the daemon accepts the deletion, without waiting for it to end.

piquelctl env deploy

Deploy an environment from its source.

For a repository-backed application, it fetches the manifest from the environment’s branch, or from --branch or --commit for this deployment only. Otherwise, it deploys the saved manifest. The command asks for confirmation and waits for the deployment. Promoted environments deploy with env promote instead.

piquelctl env deploy [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

  • --branch <BRANCH>: Fetch the repository manifest from this branch, for this deployment only.

    The environment keeps following its own branch.

  • --commit <SHA>: Fetch the repository manifest at this full commit hash, for this deployment only.

piquelctl env reconcile

Retry an environment’s latest operation with the inputs it was given.

If the operation is still in progress, the command waits for it instead of starting it again. A stopped environment starts.

piquelctl env reconcile [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

piquelctl env stop

Stop an environment, keeping its configuration, volumes and secrets.

Its routes are withdrawn and its services scale to zero. It stays stopped until env start, env reconcile, a deployment, a restore or a promotion into it; pushes don’t deploy it meanwhile. The command asks for confirmation and waits until its services have stopped. Previews are deleted instead.

piquelctl env stop [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

piquelctl env start

Start a stopped environment again.

Its services run their replicas again and its routes are served. Like env reconcile, it retries the latest operation with the inputs it was given, or waits for it while it is in progress.

piquelctl env start [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

Options:

  • --expected-generation <GENERATION>: Fail unless the application is at this generation.

    Without it, a deployment uses the generation it inspects, and a retry checks none.

  • --yes: Skip the confirmation prompt.

  • --no-wait: Return once the daemon accepts the operation, without waiting for it to end.

piquelctl env secret

List, regenerate, or delete an environment’s generated secrets.

piquelctl env secret [OPTIONS] <APPLICATION> <COMMAND>

Arguments:

  • <APPLICATION>: Application name or stable ID.

Options:

  • --env <ENV>: Environment name or stable ID. You can omit it when the application has exactly one environment.

Commands:

piquelctl env secret list

List the environment’s generated secrets.

It shows each secret’s version, never its value.

piquelctl env secret <APPLICATION> list [OPTIONS]

piquelctl env secret regenerate

Generate a new value for a generated secret.

Use it to rotate a value, or to replace one that secrets recover-key discarded. The next deployment uses it; running services keep theirs until then. Needs secrets:write.

piquelctl env secret <APPLICATION> regenerate [OPTIONS] <NAME>

Arguments:

  • <NAME>: Secret name.

Options:

  • --expected-generation <GENERATION>: Fail unless the secret is at this generation.

    Defaults to the generation it inspects.

  • -y, --yes: Skip the confirmation prompt.

piquelctl env secret delete

Delete a generated secret that nothing uses.

It fails while the configuration or a deployment still uses the secret. A later deployment that mounts it generates a new value. Needs secrets:write.

piquelctl env secret <APPLICATION> delete [OPTIONS] <NAME>

Arguments:

  • <NAME>: Secret name.

Options:

  • --expected-generation <GENERATION>: Fail unless the secret is at this generation.

    Defaults to the generation it inspects.

  • -y, --yes: Skip the confirmation prompt.

piquelctl env logs

Print the most recent lines of an environment’s Docker logs.

piquelctl env logs [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

Options:

  • --service <SERVICE>: Only show this service’s output.

    Defaults to every service.

  • --tail <TAIL>: Show at most this many of the most recent lines, from 1 to 1000, merged across services. Default: 200.

  • --since-seconds <SECONDS>: Only show output written within this many seconds, from 1 to 86400 (a day). Default: 3600.

piquelctl env history

List an environment’s deployments, newest first: each one’s outcome, where it came from, and its release.

piquelctl env history [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

Options:

  • --cursor <CURSOR>: Cursor from the previous page.
  • --limit <LIMIT>: Show at most this many deployments, from 1 to 100; 3 without it.

piquelctl env restore

Deploy an earlier, succeeded deployment again exactly as it ran: its rendered manifest, images and pinned secret versions. Jobs don’t run, and volume contents and migrations stay as they are.

piquelctl env restore [OPTIONS] <APPLICATION> <ENVIRONMENT> <DEPLOYMENT>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <ENVIRONMENT>: Environment name or stable ID.
  • <DEPLOYMENT>: The deployment to restore, as history lists it; it must have succeeded.

Options:

  • --yes: Skip the interactive confirmation prompt.
  • --no-wait: Return after the daemon accepts the restore.

piquelctl env wait

Wait until a deployment of an environment is ready.

The command never follows a newer deployment. It exits with code 3 if a newer deployment or the environment’s deletion supersedes it, 5 if it fails, and 4 when --timeout runs out. Builds usually take longer than the default --timeout.

piquelctl env wait [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

Options:

  • --deployment <ID>: ID of the deployment to wait for. By default, the latest deployment when the command starts.
  • --ready <READY>: How ready the deployment must be before the command returns. Default: runtime.
    • runtime: The deployment succeeded, and the daemon observes every service healthy.
    • routes: As runtime, and every URL of its routes is ready.

piquelctl env url

Print the URLs of an environment’s routes, and whether each is ready.

piquelctl env url [OPTIONS] <APPLICATION> [ENVIRONMENT]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [ENVIRONMENT]: Environment name or stable ID. You can omit it when the application has exactly one environment.

Options:

  • --route <NAME>: Print only the URL of the route with this name, with a warning while it is pending.

piquelctl preview

Create, inspect, deploy and delete previews: disposable deployments of a branch.

piquelctl preview [OPTIONS] <COMMAND>

Commands:

piquelctl preview create

Create a preview of a branch and deploy it.

Only for repository-backed applications. If the preview of that branch and slot already exists, the command shows it and its latest deployment without deploying it again. It fails when a new preview would exceed the daemon’s preview limits.

piquelctl preview create [OPTIONS] --branch <BRANCH> <APPLICATION>

Arguments:

  • <APPLICATION>: Application name or stable ID.

Options:

  • --branch <BRANCH>: Branch of the manifest repository to deploy. Required.
  • --slot <SLOT>: Distinguishes several previews of one branch, such as one per agent: 1 to 63 lowercase letters, digits, or hyphens, starting with a letter and ending with a letter or digit.
  • --no-wait: Return once the daemon accepts the deployment, without waiting for it to finish.

piquelctl preview deploy

Deploy the head of a preview’s branch again, or a snapshot of your Git worktree with --local.

Deploying the branch’s head replaces a local snapshot the preview runs.

piquelctl preview deploy [OPTIONS] <APPLICATION> [PREVIEW]

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • [PREVIEW]: Preview ID, slug, or branch. Omit it with --local.

Options:

  • --slot <SLOT>: The preview’s slot. Give it to address a preview with a slot by its branch, or to choose the preview --local deploys to.

  • --local: Deploy a snapshot of the Git worktree of the current directory, without pushing it.

    The snapshot has the worktree’s committed, uncommitted, and untracked files. Ignored files are left out, or sent as committed when they are tracked. The command lists the uncommitted files it sends, and deploys to the preview of the current branch and --slot, creating it if needed. Your repository is never changed. A large first upload may need a longer --timeout.

  • --full-history: Upload every commit of HEAD with the snapshot.

    By default, the command sends only the commits since the nearest ancestor of HEAD that a remote-tracking branch has, and the daemon fetches that ancestor from the application’s repository. Use this when there is no such ancestor, or the daemon can’t fetch it.

  • --branch <BRANCH>: Deploy the snapshot as the preview of this branch instead of the current one. Required when HEAD is detached.

  • --no-wait: Return once the daemon accepts the deployment, without waiting for it to finish.

piquelctl preview list

List an application’s previews with their status and branch state.

piquelctl preview list [OPTIONS] <APPLICATION>

Arguments:

  • <APPLICATION>: Application name or stable ID.

piquelctl preview show

Show one preview, its URLs, and the state of its branch.

The branch is exists, moved (past the deployed commit), gone, local (the preview runs or is deploying a local snapshot), or unknown (the repository can’t be read).

piquelctl preview show [OPTIONS] <APPLICATION> <PREVIEW>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <PREVIEW>: Preview ID, slug, or branch, matched in that order.

Options:

  • --slot <SLOT>: The preview’s slot. Needed to address a preview with a slot by its branch.

piquelctl preview logs

Print the most recent lines of a preview’s Docker logs.

piquelctl preview logs [OPTIONS] <APPLICATION> <PREVIEW>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <PREVIEW>: Preview ID, slug, or branch, matched in that order.

Options:

  • --slot <SLOT>: The preview’s slot. Needed to address a preview with a slot by its branch.

  • --service <SERVICE>: Only show this service’s output.

    Defaults to every service.

  • --tail <TAIL>: Show at most this many of the most recent lines, from 1 to 1000, merged across services. Default: 200.

  • --since-seconds <SECONDS>: Only show output written within this many seconds, from 1 to 86400 (a day). Default: 3600.

piquelctl preview history

List a preview’s deployments, newest first: each one’s outcome and where it came from.

piquelctl preview history [OPTIONS] <APPLICATION> <PREVIEW>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <PREVIEW>: Preview ID, slug, or branch, matched in that order.

Options:

  • --slot <SLOT>: The preview’s slot. Needed to address a preview with a slot by its branch.
  • --cursor <CURSOR>: Cursor from the previous page.
  • --limit <LIMIT>: Show at most this many deployments, from 1 to 100; 3 without it.

piquelctl preview restore

Deploy an earlier, succeeded deployment of a preview again exactly as it ran, without running its jobs.

piquelctl preview restore [OPTIONS] <APPLICATION> <PREVIEW> <DEPLOYMENT>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <PREVIEW>: Preview ID, slug, or branch, matched in that order.
  • <DEPLOYMENT>: The deployment to restore, as history lists it; it must have succeeded.

Options:

  • --slot <SLOT>: The preview’s slot. Needed to address a preview with a slot by its branch.
  • --yes: Skip the interactive confirmation prompt.
  • --no-wait: Return after the daemon accepts the restore.

piquelctl preview wait

Wait until a deployment of a preview is ready.

The command never follows a newer deployment. It exits with code 3 if a newer deployment or the preview’s deletion supersedes it, 5 if it fails, and 4 when --timeout runs out. Builds usually take longer than the default --timeout.

piquelctl preview wait [OPTIONS] <APPLICATION> <PREVIEW>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <PREVIEW>: Preview ID, slug, or branch, matched in that order.

Options:

  • --slot <SLOT>: The preview’s slot. Needed to address a preview with a slot by its branch.
  • --deployment <ID>: ID of the deployment to wait for. By default, the latest deployment when the command starts.
  • --ready <READY>: How ready the deployment must be before the command returns. Default: runtime.
    • runtime: The deployment succeeded, and the daemon observes every service healthy.
    • routes: As runtime, and every URL of its routes is ready.

piquelctl preview url

Print the URLs of a preview’s routes, and whether each is ready.

piquelctl preview url [OPTIONS] <APPLICATION> <PREVIEW>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <PREVIEW>: Preview ID, slug, or branch, matched in that order.

Options:

  • --slot <SLOT>: The preview’s slot. Needed to address a preview with a slot by its branch.
  • --route <NAME>: Print only the URL of the route with this name, with a warning while it is pending.

piquelctl preview exec

Run a one-off command in a running task of a preview’s service, streaming its output.

piquelctl exits with the command’s exit code. --timeout limits each request, not the session.

piquelctl preview exec [OPTIONS] <APPLICATION> <PREVIEW> <SERVICE> -- <COMMAND>...

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <PREVIEW>: Preview ID, slug, or branch, matched in that order.
  • <SERVICE>: Service that runs the command, in one of its running tasks.
  • <COMMAND>...: Program to run and its arguments, after --.

Options:

  • --slot <SLOT>: The preview’s slot. Needed to address a preview with a slot by its branch.

  • -i, --interactive: Forward standard input to the command.

  • -t, --tty: Allocate a terminal, for interactive programs such as a shell.

    It implies --interactive, and needs a terminal on standard input, which it switches to raw mode so that keys such as Ctrl-C reach the command.

piquelctl preview delete

Delete a preview and every volume it created.

The volumes’ data is lost. The command asks for confirmation and waits until the preview is gone.

piquelctl preview delete [OPTIONS] <APPLICATION> <PREVIEW>

Arguments:

  • <APPLICATION>: Application name or stable ID.
  • <PREVIEW>: Preview ID, slug, or branch, matched in that order.

Options:

  • --slot <SLOT>: The preview’s slot. Needed to address a preview with a slot by its branch.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --no-wait: Return once the daemon accepts the deletion, without waiting for it to finish.

piquelctl preview prune

Delete the previews whose branch is gone from the repository.

The command lists them and asks for confirmation. The daemon checks each branch again and keeps any preview it can no longer confirm is gone. Previews whose branch state is unknown or local are kept. Their volumes are deleted with them.

piquelctl preview prune [OPTIONS] --branch-gone <APPLICATION>

Arguments:

  • <APPLICATION>: Application name or stable ID.

Options:

  • --branch-gone: Select the previews whose branch no longer exists. Required. Required.
  • --yes: Skip the confirmation prompt. You need it when not on a terminal.
  • --no-wait: Return once the daemon accepts the deletion, without waiting for it to finish.

piquelctl builds

Inspect Git source builds and job runs, and read their output.

piquelctl builds [OPTIONS] <COMMAND>

Commands:

piquelctl builds list

List Git source builds and job runs, newest first.

piquelctl builds list [OPTIONS]

Options:

  • --application <APPLICATION_ID>: Only show the builds of the environments of the application with this ID.
  • --environment <ENVIRONMENT_ID>: Only show the builds of the environment with this ID.
  • --cursor <CURSOR>: Read the page after this cursor, which the previous page printed.

piquelctl builds logs

Read the newest page of a build’s output.

To read older output, pass the --before offset it prints. Needs logs:read.

piquelctl builds logs [OPTIONS] <ID>

Arguments:

  • <ID>: Build ID, from builds list.

Options:

  • --before <OFFSET>: Read the output before this byte offset, which the previous page printed.

piquelctl operation

Show an operation, waiting until it ends.

Deployments, deletions and other long tasks run as operations, whose IDs commands print. Unless you pass --no-wait, it exits with code 5 if the operation failed.

piquelctl operation [OPTIONS] <OPERATION_ID>

Arguments:

  • <OPERATION_ID>: Operation ID.

Options:

  • --no-wait: Show the operation’s current state instead of waiting for it to end.

piquelctl analytics

Summarize deployment outcomes, retries, durations, and failure codes over a time window, for every readable application or one environment.

piquelctl analytics [OPTIONS]

Options:

  • --app <APP>: Only deployments of this application’s environment, by name or ID; every readable application’s when omitted.
  • --env <ENV>: The environment of –app, by name or ID; required when it has several.
  • --since <SINCE>: Start this long ago, such as 24h or 7d; defaults to 30 days before the end.
  • --until <UNTIL>: End this long ago; defaults to now.

piquelctl events

Read one page of the event history, oldest first.

Events record what happened to applications, environments and the daemon, such as edits, deployments and failures.

piquelctl events [OPTIONS]

Options:

  • --application <APPLICATION_ID>: Only show events of the application with this ID, and of all its environments, including deleted ones.

  • --environment <ENVIRONMENT_ID>: Only show events of the environment with this ID, even a deleted one.

  • --kind <KIND>: Only show events of this kind, such as operation_failed.

    The dashboard’s Events page lists the kinds recorded so far.

  • --errors-only: Only show failures: events that carry an error code.

  • --cursor <CURSOR>: Read the page after this cursor, which the previous page printed.

  • --limit <LIMIT>: Show at most this many items, from 1 to 100. Default: 50.