Skip to content

cancel command

This command allows you to cancel one or more in-progress commands. If no query is provided, it cancels the most recent command from your CLI. If a query is provided, it cancels all in-progress commands matching that query.

Usage

formae cancel [OPTIONS]

Options

Option Description
--output-consumer Consumer of the command result (human | machine) [default: "human"]
--output-schema The schema to use for the result output (json | yaml). Only relevant for the "machine" output-consumer [default: "yaml"]
--query Query that allows to find commands to cancel by their attributes. If not provided, cancels the most recent command [default: ""]
--watch Watch the status of canceled commands until they complete [default: "false"]
--status-output-layout What to print as status output (summary | detailed) [default: "summary"]

Consumer

Currently, there are two consumers:

  • human (default): The CLI assumes a human user is interacting with it. Output is less strictly formatted and more verbose
  • machine: The CLI assumes the data printed to stdout will be processed by a machine or another tool

Canceling the Most Recent Command

If no query is provided, formae cancels your most recent command:

formae cancel

This is the quickest way to stop a command you just submitted that you want to cancel.

Cancellation by Query

The --query flag allows you to cancel multiple commands that match specific criteria. The query language is simple and is described in detail here.

Following fields are available for search:

  • id: the command ID
  • command: type of command. Possible values are:
    • apply: apply CLI command
    • destroy: destroy CLI command
  • status: status of the commands to search for. Possible values are (case doesn't matter):
    • InProgress: commands currently being executed
    • NotStarted: commands that are queued
  • stack: stack the related resources belong to (case sensitive)
  • client: the client ID of a CLI. Your own CLI can be referenced as client:me, or the ID found in ~/.pel/formae_cli_client_id

Here are a few examples:

  • formae cancel --query='status:inprogress': cancel all in-progress commands from this CLI
  • formae cancel --query='stack:staging': cancel commands affecting the staging stack
  • formae cancel --query='command:apply status:inprogress': cancel all in-progress apply commands
  • formae cancel --query='id:cmd_abc123xyz': cancel a specific command by ID

Understanding Cancellation

When you cancel a command, formae attempts to stop resource updates that are still pending or in progress. Only commands in InProgress or NotStarted states can be canceled.

What Happens to Resource Updates

The outcome for each resource update depends on its state when the cancellation request is processed:

  • Canceled: The resource update was successfully stopped before it started or completed. These are shown in green in detailed status output, as they represent successful cancellations.
  • Failed or Rejected: The resource update either failed or was rejected. These are shown in green in detailed status output as the resource updates did not result in infrastructure changes.
  • Completed (unable to cancel): The resource update finished executing before it could be canceled. These are shown in red in detailed status output as the user's desire was to not execute them.
  • In Progress: Updates currently executing may transition to either Canceled or Completed depending on timing. These are shown in grey.

Important: formae does not roll back completed operations. If a resource was successfully created, updated, or deleted before the cancellation took effect, that operation remains in place. Cancellation prevents pending operations from starting, but does not undo work that has already been performed.

To restore your infrastructure to the state before the canceled command, re-apply the most recent forma for the affected stack using hard reconcile mode (--mode reconcile --force). This will clean up any resources that were partially created by the canceled command and recover any resources that were destroyed before cancellation took effect. For more information about apply modes and hard reconcile, see the Workflows documentation and Classic GitOps workflow.

Watch Mode

The --watch flag enables continuous monitoring of the canceled commands until they complete:

formae cancel --watch

This is useful for confirming that the cancellation completed successfully.

Status Output Layout

When using --watch, you can control the output format using the --status-output-layout flag:

  • summary (default): Shows a compact table view with command state and resource update counts
  • detailed: Shows a detailed tree view with individual resource update states and details

Examples:

# Watch with detailed output showing individual resource updates
formae cancel --watch --status-output-layout detailed

# Watch with summary output (default)
formae cancel --watch --status-output-layout summary

Viewing Cancellation Results

To view the results of a cancellation, use the status command with the --output-layout detailed flag:

# For a specific command
formae status command --query 'id:cmd_abc123xyz' --output-layout detailed

# For all recently canceled commands
formae status command --query 'status:canceled' --output-layout detailed

Important Notes

  • Only commands in NotStarted or InProgress states can be canceled
  • If you don't provide a query, the most recent command from your CLI is canceled
  • The cancel operation is asynchronous - use status or --watch to verify the cancellation results
  • Multiple commands can be canceled in a single operation using a query
  • Cancellation prevents pending work from starting but does not roll back completed operations