CLI Command Reference

CLI Command Reference

All built-in commands available in every apijack-generated CLI. Replace <cli> with your CLI's name (e.g., apijack).

---

setup / login

Syntax: <cli> setup or <cli> login

Interactively configure a new environment — prompts for environment name, URL, and credentials, then saves and switches to the new environment. login is an alias for setup.

Flags:

Flag	Description
--allow-insecure-storage	Allow plaintext credential storage for production (non-localhost) URLs

Example:

<cli> setup
# Prompts: environment name, URL, username, password

---

config list

Syntax: <cli> config list

List all configured environments. The active environment is marked with *.

Flags: none

Example:

$ <cli> config list
* dev     http://localhost:8080  admin
  staging https://staging.example.com  deploy

---

config switch

Syntax: <cli> config switch <name>

Switch the active environment. All subsequent commands use the URL and credentials of the named environment.

Each environment keeps its own cached session, so switching away and back doesn't log you out. To run one command against another environment without switching, use the global --config <name>.

Arguments:

Argument	Description
<name>	Name of the environment to activate

Flags: none

Example:

<cli> config switch staging

---

config clear-session

Syntax: <cli> config clear-session [name] [--all]

Delete a cached session so the next command logs in again. With no name it clears the session the next command would use: the environment selected with --config; otherwise the <CLI>_URL / _USER / _PASS credentials, if set; otherwise the active environment.

Arguments:

Argument	Description
[name]	Environment whose session to delete. An unknown name exits 1 with the list of configured environments

Flags:

Flag	Type	Description
--all	flag	Delete every environment's cached session. Can't be combined with a name

Examples:

<cli> config clear-session
<cli> config clear-session staging
<cli> config clear-session --all

---

config import

Syntax: <cli> config import [alias]

Import a pre-configured known site by alias — only credentials are required. If alias is omitted, an interactive menu is shown. Only available when the CLI is built with knownSites configured.

Flags:

Flag	Type	Description
--user <email>	string	Email for authentication (skips prompt)
--password <password>	string	Password for authentication (skips prompt)
--allow-insecure-storage	flag	Allow plaintext storage for production URLs

Example:

<cli> config import production --user admin@example.com

---

config update-password

Syntax: <cli> config update-password [name]

Update the stored password for an environment. Defaults to the active environment if name is omitted.

Flags:

Flag	Type	Description
--password <password>	string	New password (skips prompt)

Example:

<cli> config update-password staging --password newsecret

---

generate

Syntax: <cli> generate

Regenerate CLI source files from the active environment's OpenAPI spec. Fetches the spec from the configured URL and writes types.ts, client.ts, commands.ts, and command-map.ts to the generated directory.

Flags: none

Example:

<cli> generate

---

routine list

Syntax: <cli> routine list [path]

List available routines. Optionally drill into a group by providing a path prefix.

Arguments:

Argument	Description
[path]	Optional group prefix to filter by (e.g., pets)

Flags:

Flag	Description
--tree	Show full tree structure instead of flat list

Examples:

<cli> routine list
<cli> routine list --tree
<cli> routine list pets

---

routine run

Syntax: <cli> routine run <name>

Execute a routine by name. Steps are run in order; progress is printed to stdout (unless --json or -s/--quiet is passed). Exits with code 1 if any step fails.

Arguments:

Argument	Description
<name>	Routine name or path (e.g., my-routine or pets/create-and-verify)

Flags:

Flag	Type	Description
--set <pairs...>	key=value	Override routine variables at runtime; repeatable
--dry-run	flag	Print resolved commands without executing any API calls
--json	flag	Emit the RoutineResult as JSON to stdout (silences progress output)
-s, --quiet	flag	Print only what the routine's commands print: no banner, step lines or summary. Failures still go to stderr

--quiet and --json can't be combined. --quiet --dry-run prints only the resolved commands.

Examples:

<cli> routine run create-pet
<cli> routine run create-pet --set pet_name=Luna --set pet_age=2
<cli> routine run create-pet --dry-run
<cli> routine run create-pet --json
<cli> routine run create-pet -s
<cli> --config staging routine run create-pet

---

routine validate

Syntax: <cli> routine validate <name>

Validate a routine YAML file for structural correctness without executing it. Exits with code 1 and prints errors if invalid.

Arguments:

Argument	Description
<name>	Routine name to validate

Flags: none

Example:

<cli> routine validate create-pet

---

routine test

Syntax: <cli> routine test <name>

Run a routine's spec (test) file. Executes the spec routine and evaluates all assert: blocks. Exits with code 1 if any assertion fails.

Arguments:

Argument	Description
<name>	Routine name whose spec file to run

Flags:

Flag	Type	Description
--set <pairs...>	key=value	Override variables in the spec routine; repeatable

Example:

<cli> routine test create-pet
<cli> routine test create-pet --set pet_name=TestBuddy

---

routine init

Syntax: <cli> routine init

Copy built-in routines (bundled with the CLI) into ~/.<cli>/routines/ so they appear in routine list and can be run or customized.

Flags: none

Example:

<cli> routine init

---

plugin install

Syntax: <cli> plugin install

Register this CLI as a Claude Code plugin, exposing all commands and routines as MCP tools. Builds the MCP server bundle if needed, then writes the plugin registration to ~/.claude/.

Flags:

Flag	Type	Description
--cli-invocation <args...>	string(s)	How to invoke this CLI (default: current process argv)
--generated-dir <dir>	string	Path to the generated files directory (default: src/generated)

Example:

<cli> plugin install
<cli> plugin install --cli-invocation bun run src/cli.ts

After installing, run /reload-plugins inside Claude Code to activate.

---

plugin uninstall

Syntax: <cli> plugin uninstall

Remove the Claude Code plugin registration written by plugin install.

Flags: none

Example:

<cli> plugin uninstall

---

plugin config add-cidr

Syntax: <cli> plugin config add-cidr <cidr>

Add a CIDR range to the plugin's allowed list for network access.

Arguments:

Argument	Description
<cidr>	CIDR range to allow (e.g., 192.168.1.0/24)

Example:

<cli> plugin config add-cidr 10.0.0.0/8

---

plugin config remove-cidr

Syntax: <cli> plugin config remove-cidr <cidr>

Remove a CIDR range from the plugin's allowed list.

Example:

<cli> plugin config remove-cidr 10.0.0.0/8

---

plugin config list

Syntax: <cli> plugin config list

Show the current plugin configuration as JSON.

Example:

<cli> plugin config list

---

mcp

Syntax: <cli> mcp

Start an MCP (Model Context Protocol) server that exposes all CLI commands and routines as tools for AI agents. Requires @modelcontextprotocol/sdk to be installed.

Flags: none

Example:

<cli> mcp

---

upgrade

Syntax: <cli> upgrade

Check npm for the latest version of @apijack/core and install it if a newer version is available. Also re-runs plugin install to update the Claude Code plugin registration.

Flags: none

Example:

<cli> upgrade

---

Global option: --config <name>

Syntax: <cli> --config <name> <command> [args...]

Run a single invocation against any environment in config.json, without changing the active one.

<cli> --config staging pets list
<cli> --config staging routine run create-pet --set pet_name=Luna   # every step and sub-routine uses staging

• Uses that environment's URL, credentials, auth type, sessionAuth / refreshOn and its own session file. It wins over <CLI>_URL / _USER / _PASS.
• It goes before the command; --config=<name> works too. A --config after the command belongs to that command (e.g. a generated flag for an API field named config); a command without one rejects it with a hint to move it.
• An unknown name fails with the list of configured environments.
• <cli> --config <name> mcp passes the environment on to every CLI call the MCP server makes.
• Programmatic: runRoutine(name, { config: '<name>' }), or createCli({ environment: '<name>', ... }) (a leading --config still wins).

---

Global Flags (Generated API Commands)

These flags apply to generated API commands (commands produced by generate, not the built-in commands above).

Flag	Values	Description
-o <format>	json, table, quiet, routine-step, curl, curl-with-creds	Set output format
--dry-run	—	Preview the API request without executing it

Output Formats

Value	Description
json	Pretty-printed JSON (default)
table	Render response as an ASCII table (arrays of objects only)
quiet	Suppress all output
routine-step	Print the YAML step definition for use in a routine instead of executing
curl	Print a curl command equivalent to the request (credentials omitted)
curl-with-creds	Print a curl command with credentials included

Example:

<cli> pets list -o table
<cli> pets create --name Buddy -o routine-step
<cli> pets get --id 1 -o curl
<cli> pets list --dry-run