Command Reference

Complete reference for all IBM i CLI commands, options, and usage examples.

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.

ibmi related <library> <object>

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.