Command Discovery

Command Discovery

Overview

Append -o routine-step to any CLI command to output its YAML step definition instead of executing it. This is the primary way to discover command signatures for building routines — it shows you exactly how to wire a command into a routine, including which args are required and which are optional.

Basic Usage

Without the flag, a command runs normally:

apijack pets create-pet --name "Buddy" --species dog --age 3
# Output: { "id": 6, "name": "Buddy", "species": "dog", "age": 3, "status": "available" }

With -o routine-step, nothing is executed. Instead, the YAML step definition is printed:

apijack pets create-pet --name "Buddy" --species dog --age 3 -o routine-step

Output:

- name: create-pet
  command: pets create-pet
  args:
    --name: "Buddy"
    --species: "dog"
    --age: "3"

Copy this directly into a routine file as a starting point.

Reading the Output

The step output tells you everything you need to know about a command's interface.

Required args appear as active (uncommented) lines with the values you provided:

args:
  --name: "Buddy"
  --species: "dog"
  --age: "3"

Optional args appear as commented-out lines with an # optional annotation and a description of accepted values:

apijack pets list -o routine-step

- name: list
  command: pets list
  args:
    # --species: "" # optional — Filter pets by species [dog, cat, bird, fish, rabbit]
    # --status: "" # optional — Filter pets by status [available, pending, adopted]

To use an optional arg, uncomment the line and fill in the value. The annotations show accepted values, so you can see constraints without consulting separate documentation.

Building Routines from Discovery

The typical workflow for authoring a new routine:

1. Run the command you want with -o routine-step
2. Copy the YAML output into your routine file
3. Replace hardcoded values with variables ($variable_name)
4. Add output: to capture results for later steps
5. Connect steps with variable references ($alias.field)

Example Workflow

This example builds a routine that creates a pet and then retrieves it to confirm the result.

Step 1: Discover the create-pet signature

apijack pets create-pet --name "Buddy" --species dog --age 3 -o routine-step

- name: create-pet
  command: pets create-pet
  args:
    --name: "Buddy"
    --species: "dog"
    --age: "3"

Step 2: Discover the get signature

apijack pets get --id 1 -o routine-step

- name: get
  command: pets get
  args:
    --id: "1"

Step 3: Compose into a routine

With both signatures in hand, compose a routine. Add output: created to the first step to capture its response, then reference $created.id in the second step:

name: create-and-verify-pet
description: Create a pet and retrieve it to confirm the result

variables:
  pet_name: "Buddy"
  pet_species: "dog"
  pet_age: "3"

steps:
  - name: create-pet
    command: pets create-pet
    args:
      --name: "$pet_name"
      --species: "$pet_species"
      --age: "$pet_age"
    output: created

  - name: get-pet
    command: pets get
    args:
      --id: "$created.id"

Run it:

apijack routine run create-and-verify-pet
# or override a variable at runtime:
apijack routine run create-and-verify-pet --set pet_name="Luna"

See Writing Routines for the full routine YAML reference, including conditions, loops, and assertions.