Command Reference

All commands follow the pattern ibmi <command> [arguments] [options]. Global options (--system, --format, --raw, --stream, --watch, --output, --tools, --no-color) apply to every command.

SQL Execution

`ibmi sql [statement]`

Execute a SQL query against the target system.

ibmi sql "SELECT * FROM SAMPLE.EMPLOYEE FETCH FIRST 10 ROWS ONLY"
ibmi sql --file query.sql
cat query.sql | ibmi sql
ibmi sql "SELECT * FROM SAMPLE.EMPLOYEE" --dry-run
ibmi sql "SELECT * FROM SAMPLE.EMPLOYEE" --format csv --output results.csv
ibmi sql "SELECT JOB_NAME FROM TABLE(QSYS2.ACTIVE_JOB_INFO())" --watch 5

Option	Description	Default
`--file <path>`	Read SQL from a file	—
`--limit <n>`	Maximum rows returned	system `maxRows` (5000)
`--read-only` / `--no-read-only`	Enforce or disable read-only mode	`--read-only`
`--dry-run`	Print resolved SQL without executing	—

SQL source priority: positional argument > --file > piped stdin.

Read-only mode is enabled by default. To execute INSERT, UPDATE, DELETE, or DDL statements, pass --no-read-only explicitly or set readOnly: false in your system config.

Multi-System Execution

Run the same SQL query against multiple IBM i systems in parallel by passing a comma-separated list of system names to --system. Each system name must be defined in your CLI configuration file — either the user-level config at ~/.ibmi/config.yaml or a project-level .ibmi/config.yaml.

Multi-system execution requires named system connections. Ad-hoc DB2i_* environment variables only define a single system. See Getting Started for setup instructions and Configuration for managing multiple systems.

Usage

# Query two systems in parallel
ibmi sql "SELECT * FROM SAMPLE.EMPLOYEE FETCH FIRST 5 ROWS ONLY" --system dev,prod

# JSON output includes per-system metadata
ibmi sql "SELECT JOB_NAME, JOB_STATUS FROM TABLE(QSYS2.ACTIVE_JOB_INFO()) FETCH FIRST 10 ROWS ONLY" \
  --system dev,prod --format json

# NDJSON streaming for pipeline consumption
ibmi sql "SELECT * FROM QSYS2.SYSTEM_STATUS_INFO" --system dev,prod --stream --format json

Output format

Each row in the output includes a SYSTEM column identifying which system returned it. The JSON envelope includes a systems array with per-system row counts, timing, and any errors:

{
  "ok": false,
  "data": [
    { "SYSTEM": "dev", "EMPNO": "000010", "FIRSTNME": "CHRISTINE", ... },
    { "SYSTEM": "prod", "ERROR": "connect ECONNREFUSED ..." }
  ],
  "systems": [
    { "system": "dev", "host": "dev.example.com", "rows": 5, "elapsed_ms": 413 },
    { "system": "prod", "host": "prod.example.com", "rows": 0, "error": "connect ECONNREFUSED ..." }
  ],
  "meta": {
    "total_rows": 5,
    "systems_queried": 2,
    "systems_ok": 1,
    "systems_failed": 1
  }
}

Limitations

--watch is not supported with multiple systems.
If one system is unreachable, its results appear as an error row without affecting the other systems.
All systems share the same --limit value. When no --limit is specified, the smallest maxRows across all target systems is used.

Schema Discovery

`ibmi schemas`

List available schemas (libraries) on the system.

ibmi schemas
ibmi schemas --filter "MY%"
ibmi schemas --system-schemas         # include Q* and SYS* schemas
ibmi schemas --limit 20 --offset 40   # pagination

Option	Description	Default
`--filter <pattern>`	SQL LIKE pattern to filter schema names	—
`--system-schemas`	Include system schemas (Q* and SYS*)	`false`
`--limit <n>`	Rows per page	`50`
`--offset <n>`	Skip rows for pagination	`0`

`ibmi tables <schema>`

List tables, views, and physical files in a schema.

ibmi tables SAMPLE
ibmi tables QSYS2 --filter "SYS%"

Option	Description	Default
`--filter <pattern>`	SQL LIKE pattern to filter table names	—
`--limit <n>`	Rows per page	`50`
`--offset <n>`	Skip rows for pagination	`0`

`ibmi columns <schema> <table>`

Get column metadata for a specific table.

ibmi columns SAMPLE EMPLOYEE

Returns column name, data type, length, nullable, default value, description, and ordinal position. Discover objects that depend on a database file (views, indexes, triggers, foreign keys, logical files).

ibmi related SAMPLE EMPLOYEE
ibmi related SAMPLE EMPLOYEE --type INDEX

Option	Description	Default
`--type <type>`	Filter by dependency type (e.g., INDEX, VIEW, TRIGGER)	—

`ibmi describe <objects>`

Generate DDL (CREATE statements) for one or more SQL objects using QSYS2.GENERATE_SQL.

# Single object
ibmi describe "SAMPLE.EMPLOYEE"

# Multiple objects (comma-separated)
ibmi describe "SAMPLE.EMPLOYEE,SAMPLE.DEPARTMENT"

# Explicit type for non-table objects
ibmi describe "QSYS2.SYSCOLUMNS" --type VIEW

# Unqualified name (defaults library to QSYS2)
ibmi describe "SYSCOLUMNS" --type VIEW

# JSON output
ibmi describe "SAMPLE.EMPLOYEE,SAMPLE.DEPARTMENT" --format json

Option	Description	Default
`--type <type>`	Object type	`TABLE`

Valid --type values: ALIAS, CONSTRAINT, FUNCTION, INDEX, MASK, PERMISSION, PROCEDURE, SCHEMA, SEQUENCE, TABLE, TRIGGER, TYPE, VARIABLE, VIEW, XSR Objects are specified as LIBRARY.OBJECT or just OBJECT (defaults to QSYS2). When describing multiple objects, each is queried independently — a failure on one object produces an ERROR: row without affecting the others.

`ibmi validate "<sql>"`

Validate SQL syntax and verify referenced objects exist without executing the query.

ibmi validate "SELECT * FROM SAMPLE.EMPLOYEE WHERE SALARY > 50000"

Uses QSYS2.PARSE_STATEMENT and cross-references tables, columns, and routines against the system catalog.

YAML Tool Execution

`ibmi tool <name>`

Execute a YAML-defined SQL tool. Requires --tools to specify the YAML file(s).

ibmi tool system_status --tools ./tools/performance/performance.yaml
ibmi tool active_job_info --limit 20 --tools ./tools/performance/performance.yaml
ibmi tool memory_pools --dry-run --tools ./tools/performance/performance.yaml

Each tool’s YAML parameters are automatically converted to CLI flags. Parameter names are converted from snake_case to --kebab-case:

# YAML parameter: schema_name → CLI flag: --schema-name
parameters:
  - name: schema_name
    type: string
    required: true

Option	Description
`--dry-run`	Show resolved SQL and parameters without executing

`ibmi tools`

List available tools from loaded YAML files.

ibmi tools --tools ./tools/
ibmi tools --toolset work_management --tools ./tools/
ibmi tools show system_status --tools ./tools/

Subcommand	Description
(default)	List all available tools
`show <name>`	Show tool details (parameters, SQL statement)

Option	Description
`--toolset <name>`	Filter tools by toolset

`ibmi toolsets`

List available toolsets from loaded YAML files.

ibmi toolsets --tools ./tools/

System Management

`ibmi system <subcommand>`

Manage named system connections in .ibmi/config.yaml.

ibmi system list                          # list all configured systems
ibmi system show dev                      # show system details
ibmi system add dev --host h --user u     # add (prompts for missing fields)
ibmi system remove dev                    # remove a system
ibmi system default dev                   # set default system
ibmi system test dev                      # test connectivity
ibmi system test --all                    # test all systems
ibmi system config-path                   # show config file locations

Subcommand	Description
`list`	Show all configured systems
`show <name>`	Display details for a specific system
`add <name>`	Add a new system connection
`remove <name>`	Remove a system connection
`default <name>`	Set the default system
`test [name]`	Test connectivity (`--all` for all systems)
`config-path`	Show config file locations

Shell Completions

`ibmi completion [shell]`

Generate shell completion scripts for tab-completion of commands, options, and arguments.

# Auto-detect shell
eval "$(ibmi completion)"

# Explicit shell
eval "$(ibmi completion bash)"    # add to ~/.bashrc
eval "$(ibmi completion zsh)"     # add to ~/.zshrc
ibmi completion fish | source     # add to Fish config

Supports bash, zsh, and fish.

Getting Started

Usage Guide

Advanced

SQL Execution

`ibmi sql [statement]`

Multi-System Execution

Usage

Output format

Limitations

Schema Discovery

`ibmi schemas`

`ibmi tables <schema>`

`ibmi columns <schema> <table>`

`ibmi describe <objects>`

`ibmi validate "<sql>"`

YAML Tool Execution

`ibmi tool <name>`

`ibmi tools`

`ibmi toolsets`

System Management

`ibmi system <subcommand>`

Shell Completions

`ibmi completion [shell]`

Getting Started

Usage Guide

Advanced

Documentation Index

​SQL Execution

​ibmi sql [statement]

​Multi-System Execution

​Usage

​Output format

​Limitations

​Schema Discovery

​ibmi schemas

​ibmi tables <schema>

​ibmi columns <schema> <table>

​ibmi related <library> <object>

​ibmi describe <objects>

​ibmi validate "<sql>"

​YAML Tool Execution

​ibmi tool <name>

​ibmi tools

​ibmi toolsets

​System Management

​ibmi system <subcommand>

​Shell Completions

​ibmi completion [shell]

SQL Execution

`ibmi sql [statement]`

Multi-System Execution

Usage

Output format

Limitations

Schema Discovery

`ibmi schemas`

`ibmi tables <schema>`

`ibmi columns <schema> <table>`

`ibmi related <library> <object>`

`ibmi describe <objects>`

`ibmi validate "<sql>"`

YAML Tool Execution

`ibmi tool <name>`

`ibmi tools`

`ibmi toolsets`

System Management

`ibmi system <subcommand>`

Shell Completions

`ibmi completion [shell]`