Quickstart

Quickstart

Get from zero to a working CLI in under 5 minutes using the Petstore example API.

1. Install apijack

bun install -g @apijack/core

Or with npm:

npm install -g @apijack/core

2. Start the example API

See Petstore Example App for full details. Quick start:

git clone https://github.com/Premo-Cloud/apijack-petstore-example.git
cd apijack-petstore-example
bun run start

The server runs on port 3459 with credentials admin / password.

3. Connect to the API

Run apijack setup and follow the prompts:

$ apijack setup

Environment name: petstore
API base URL: http://localhost:3459
Username: admin
Password: ********

Fetching OpenAPI spec from http://localhost:3459/v3/api-docs...
Generating CLI...

Done! Configured environment "petstore".
Generated 11 commands across 2 groups.

apijack fetches the OpenAPI spec, generates typed commands, and saves everything to ~/.apijack/. You're ready to use the CLI immediately.

4. Explore commands

List all pets:

$ apijack pets list
[
  { "id": 1, "name": "Buddy",    "species": "dog",    "age": 3, "status": "adopted",    "ownerId": 1 },
  { "id": 2, "name": "Whiskers", "species": "cat",    "age": 2, "status": "available",  "ownerId": null },
  { "id": 3, "name": "Goldie",   "species": "fish",   "age": 1, "status": "available",  "ownerId": null },
  { "id": 4, "name": "Rex",      "species": "dog",    "age": 5, "status": "adopted",    "ownerId": 2 },
  { "id": 5, "name": "Luna",     "species": "cat",    "age": 1, "status": "pending",    "ownerId": null }
]

List all owners:

$ apijack owners list
[
  { "id": 1, "name": "Alice Johnson", "email": "alice@example.com" },
  { "id": 2, "name": "Bob Smith",     "email": "bob@example.com" }
]

Filter by species:

$ apijack pets list --species cat
[
  { "id": 2, "name": "Whiskers", "species": "cat", "age": 2, "status": "available", "ownerId": null },
  { "id": 5, "name": "Luna",     "species": "cat", "age": 1, "status": "pending",   "ownerId": null }
]

Get a single pet by ID:

$ apijack pets get 1
{
  "id": 1,
  "name": "Buddy",
  "species": "dog",
  "age": 3,
  "status": "adopted",
  "ownerId": 1
}

5. Create and modify resources

Create a new pet:

$ apijack pets create-pet --name "Charlie" --species bird --age 2
{
  "id": 6,
  "name": "Charlie",
  "species": "bird",
  "age": 2,
  "status": "available",
  "ownerId": null
}

Verify it was saved:

$ apijack pets get 6
{
  "id": 6,
  "name": "Charlie",
  "species": "bird",
  "age": 2,
  "status": "available",
  "ownerId": null
}

6. Your first routine

Routines are YAML files that chain commands together with variables, assertions, and cleanup steps. Save this to .apijack/routines/hello-petstore.yaml:

name: hello-petstore
description: Create a pet, verify it, then clean up
variables:
  pet_name: "Wiki Pet"
steps:
  - name: create
    command: pets create-pet
    args:
      --name: "$pet_name"
      --species: "rabbit"
      --age: "1"
    output: new_pet

  - name: verify
    command: pets get
    args:
      --id: "$new_pet.id"
    assert: "$verify.name == $pet_name"

  - name: cleanup
    command: pets delete
    args:
      --id: "$new_pet.id"

Run it:

$ apijack routine run hello-petstore

[create] POST /pets
  {"id": 7, "name": "Wiki Pet", "species": "rabbit", "age": 1, "status": "available", "ownerId": null}

[verify] GET /pets/7
  Assertion passed: $.name == "Wiki Pet"

[cleanup] DELETE /pets/7
  {"id": 7, "name": "Wiki Pet", "species": "rabbit", "age": 1, "status": "available", "ownerId": null}

Routine completed: 3/3 steps passed.

Override the pet name at runtime with --set:

apijack routine run hello-petstore --set pet_name="Flopsy"

Next steps

• Writing Routines — variables, loops, conditions, assertions, and sub-routines
• Managing Environments — configure dev, staging, and prod environments
• Building a CLI — embed apijack in your own project with custom auth and commands