Add a custom CLI command

A wrapper lets you add a workflow while forwarding ordinary commands to the generated executable. The example below adds parcel track <shipment_id> for Parcel, a fictional delivery API with a generated shipments get command.

The wrapper requires Bash and jq. Your generated CLI remains a standalone executable; these are dependencies of the custom wrapper you choose to distribute.

Add the wrapper

Build your CLI using its generated README, naming the executable parcel-api. Put it beside this executable file named parcel:

#!/usr/bin/env bash
set -euo pipefail

script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
api="$script_dir/parcel-api"

if [[ "${1:-}" != "track" ]]; then
  exec "$api" "$@"
fi

if [[ "${2:-}" == "--help" ]]; then
  printf 'Usage: parcel track <shipment_id>\n'
  exit 0
fi
if [[ "$#" -ne 2 ]]; then
  printf 'Usage: parcel track <shipment_id>\n' >&2
  exit 2
fi

"$api" shipments get "$2" --mode agent \
  | jq '{shipment_id: .shipment_id, status: .status, tracking_url: .tracking_url}'

The sample fields must match your API's response. set -o pipefail preserves a failed API call's nonzero status even if jq succeeds. Argument arrays and quoting keep shipment IDs and forwarded flags separate from shell code.

Make the wrapper executable and try its local help:

chmod +x parcel
./parcel track --help
./parcel shipments get --help

Reuse authentication

Forwarded commands run the same generated executable with its existing environment and saved credentials. For example, ./parcel login forwards to parcel-api login. Keep the CLI's configured command identity stable so saved settings continue to resolve to the same location.

The wrapper does not read credential files or print secrets. Supply credentials through the CLI's supported inputs; see Authentication.

Preserve and distribute your command

Keep the wrapper as a separate customer-owned file in the Target's repository. Add a customer check for its syntax and mocked success and failure cases under package checks. Include both the wrapper and the correct executable for the recipient's operating system in your release archive.

After regeneration, review the Draft and run those checks. If the Spec renames shipments get or changes its response, update the wrapper in the same review. See Customize generated packages for ownership and conflict handling.

For workflows with prerequisites, polling, and resumable state, see Build a custom workflow.