IBM i CLI

A lightweight command-line interface for querying, exploring, and managing IBM i systems directly from your terminal.

The ibmi CLI lets you interact with IBM i systems without starting the MCP server. Run SQL queries, explore schemas, execute YAML-defined tools, and manage multiple system connections — all from your terminal.

---

Why Use the CLI?

Direct Access

Query IBM i databases and explore schemas without configuring an MCP client or AI agent

Multi-System

Configure and switch between development, test, and production systems with named connections

Agent-Friendly

Structured JSON output, NDJSON streaming, semantic exit codes, and dry-run mode for AI agent integration

YAML Tool Support

Execute any YAML-defined SQL tool as a CLI command with automatic parameter mapping

---

Quick Example

# Add a system connection
ibmi system add dev --host myhost.com --user MYUSER --password '${DB2i_PASS}'

# Run a query
ibmi sql "SELECT * FROM SAMPLE.EMPLOYEE FETCH FIRST 5 ROWS ONLY"

# Explore schema metadata
ibmi schemas
ibmi tables SAMPLE
ibmi columns SAMPLE EMPLOYEE

# Execute a YAML tool
ibmi tool system_status --tools ./tools/performance/performance.yaml

If you already have DB2i_HOST, DB2i_USER, and DB2i_PASS environment variables set (from your MCP server .env file), the CLI picks them up automatically — no additional configuration needed.

---

How It Works

The CLI reuses the same tool logic functions that power the MCP server’s built-in tools. When you run ibmi schemas, it calls the same listSchemasLogic function that the MCP server uses when an AI agent invokes the list_schemas tool. This means you get identical query behavior and results whether you’re using the CLI directly or going through an MCP client.

For YAML-defined tools, the CLI loads tool definitions and dynamically converts YAML parameters into Commander.js options — snake_case parameter names become --kebab-case flags automatically.

---

Installation

NPM Package (Recommended)

The CLI ships with the @ibm/ibmi-mcp-server package:

# Run directly with npx
npx -y @ibm/ibmi-mcp-server@latest ibmi --help

# Or install globally
npm install -g @ibm/ibmi-mcp-server
ibmi --help

Build from Source

git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server/server
npm install
npm run build
npm link

ibmi --help

---

Next Steps

Getting Started

Set up your first system connection and run your first query

Command Reference

Complete reference for all CLI commands and options

Configuration

Multi-system config files, environment variables, and resolution chain

Agent Integration

Use the CLI in scripts, pipelines, and AI agent workflows