iCli — IspBills AI Terminal

iCli is a command-line interface for IspBills that brings your iCopilot AI network engineer to any terminal.

Ask it anything your NOC team would ask:

icli "is vlan 82 in use across my network?"
icli "show all ONUs on olt#1"
icli "which customer is using IP 10.10.1.50?"
icli "check high optical signal on main OLT"

Requirements

• Node.js 18 or later
• A running IspBills instance
• An operator account (group admin, operator, or NOC user)

Quick start (npx — no install)

npx ispbills-icli

On first run iCli will ask for your instance URL, email, and password. Credentials are saved to ~/.config/ispbills-icli/config.json (mode 600 — readable only by you).

Permanent install

npm install -g ispbills-icli
icli

Uninstall

Remove the global package:

npm uninstall -g ispbills-icli

This only removes the CLI itself — your saved config/credentials, session history, and memory are kept on disk in case you reinstall later. To remove those too:

rm -rf ~/.config/ispbills-icli

Usage

Interactive REPL

$ icli

  Session   Issues   Pull requests   Gists

  ╭─╮╭─╮
  ╰─╯╰─╯  iCopilot uses AI.
  █ ▘▝ █  /help
   ▔▔▔▔

  ● Tip: /vlan
    └ Check whether a VLAN id is free across your whole fleet

  ❯ is vlan 82 free on all devices?

  ◐ Delegating this across the fleet, one sub-agent per device…

  $ Search Searching vendor docs: vsol vlan usage command
    vsol vlan usage command

  ● Fleet check whether VLAN 82 is in use
    ├ 1/3 nas#1 — FREE
    ├ 2/3 nas#2 — FREE
    └ 3/3 olt#1 — FREE

  ● VLAN 82 is free across all 3 reachable devices in your fleet.

 /srv                                                        Session: 0 tokens
 ────────────────────────────────────────────────────────────────────────────
 ❯
 ────────────────────────────────────────────────────────────────────────────
  / commands · ? help · → next tab                                        Auto

The interactive shell reproduces the GitHub Copilot CLI 1.0.70 layout: a home tab bar, the blinking mascot, one breathing line, a bottom-anchored bordered input and a live status line. Reasoning streams inline above the answer with a ◐ glyph, tool and sub-agent activity render as compact rows you can click or expand with Ctrl+O / Ctrl+E, and the input rules/footer are tinted by the active mode (interactive → plan → autopilot, cycled with Shift+Tab).

Single-shot query

icli "check uptime on all routers"
icli "show customers with overdue invoices"
icli "what is the RX power on olt#1?"
icli --reasoning "audit the config on olt#1"   # stream reasoning inline

Commands

| Command | Description | |---|---| | icli | Start interactive REPL | | icli "question" | Single question, then exit | | icli login | Re-authenticate (or switch instance) | | icli logout | Log out and clear saved credentials | | icli update | Update iCli to the latest version | | icli whoami | Show current login info | | icli --version | Show the installed iCli version | | icli --help | Show help |

Flags

| Flag | Description | |---|---| | --reasoning | Stream the model's reasoning inline (on by default in the REPL) | | --no-reasoning | Hide the reasoning trace | | --loader-style STYLE | Thinking indicator: spinner (default), gradient, or minimal | | --ascii | Force ASCII-safe glyphs (use if symbols show as boxes) | | --unicode | Force full Unicode glyphs |

On classic Windows cmd.exe iCli auto-switches to ASCII-safe symbols. If it guesses wrong, force it with icli --ascii (or set the ICLI_ASCII=1 environment variable). For the full Unicode look, use Windows Terminal or pass --unicode.

Slash commands & keys (REPL)

Type / to open the command menu. It filters as you type, shows an inline suggestion (accept with Tab or →), and runs the highlighted command on Enter.

Devices & diagnostics

| Slash | Description | |---|---| | /check [device] | Run full diagnostics on a device | | /status [device] | Health summary across the fleet | | /reachable | Which devices are up / unreachable | | /uptime [device] | Device uptime and last reboot | | /cpu [device] | CPU, memory and temperature load | | /interfaces [device] | Interface / port status and errors | | /config [device] | Show the running configuration | | /audit [device] | Audit config and suggest fixes | | /backup [device] | Back up the device configuration | | /reboot [device] | Reboot a device (asks to confirm) | | /alarms | Active alarms and recent faults |

Access network

| Slash | Description | |---|---| | /onu [id] | ONU status and signal levels | | /optical [device] | Optical RX/TX power (dBm) | | /vlan [id] | VLAN usage — free or in use | | /pppoe [user] | PPPoE session detail | | /online · /offline | Online / offline customers & ONUs | | /bandwidth [device] | Traffic / bandwidth usage |

Lookups

| Slash | Description | |---|---| | /mac [addr] | Locate a MAC address on the network | | /arp [device] · /route [device] | ARP / routing tables | | /overlaps [ip/vlan/bgp/route] | Find overlapping IP subnets, VLAN ids, interface assignments, BGP prefixes or routes | | /flapping [device] | List flapping interfaces (frequent up/down transitions) | | /dhcp | DHCP leases and pool usage | | /ping [host] · /trace [host] | Ping / traceroute a host | | /customer [name/IP] | Look up a customer |

Backups & version control

| Slash | Description | |---|---| | /backup [device] | Back up device config (all devices if omitted). Each answer is archived to your per-user git repo | | /git [args] | Run git in that backup repo — e.g. /git status, /git log, /git commit -m "note", /git remote add origin <url>, /git push | | /gist | Save the last answer or the whole transcript to a secret GitHub gist (uses the gh CLI, or /gist token <TOKEN>) |

Memory

| Slash | Description | |---|---| | /remember <note> | Save a standing note the AI keeps in mind on every turn | | /memory | List your saved memory notes | | /forget <n/all> | Delete a note by number, matching text, or all | | /copy | Copy the last AI answer to the system clipboard |

Session

| Slash | Description | |---|---| | /autopilot | Toggle autopilot — proposed fixes are applied automatically (also Shift+Tab) | | /model [name] | Show or set the AI model | | /reasoning | Toggle reasoning display (also Ctrl+T) | | /new · /history · /clear | Reset conversation · show history · clear screen | | /update · /logout · /help · /exit | Update · log out · help · quit |

Keys

| Key | Action | |---|---| | Enter | Send message (or run the highlighted slash command) | | / then ↑/↓ | Open the slash menu and move the selection; Tab / → completes, Enter runs | | @ | Mention a device/entity (e.g. @olt:, @onu:); Tab / → completes the tag | | ↑/↓ (empty input) | Navigate input history | | Ctrl+Z / Ctrl+Y | Undo / redo the input line | | Paste | Multi-line pastes (incl. mouse right-click) keep their line breaks and are never auto-submitted — press Enter to send | | Shift+Tab | Toggle autopilot mode | | Ctrl+T | Toggle reasoning display | | Ctrl+L | Clear the transcript | | Esc | Cancel the in-flight request | | Ctrl+C | Cancel a running request; press again on an empty prompt to exit | | Ctrl+A/E | Jump to start / end of the line | | Ctrl+U/K/W | Delete to start / to end / previous word |

Autopilot — when on (⚡ shown in the footer), any fix the AI proposes as a plan is applied automatically without waiting for you to type apply fix. Toggle it with Shift+Tab or /autopilot.

The REPL renders inline in your terminal's normal buffer — exactly like GitHub Copilot CLI. The banner prints once at the top and scrolls away into your native scrollback as the conversation grows, so you can scroll back through the entire session with your terminal's own scrollbar/wheel. The input box stays at the bottom while a request is in flight, and each answer (including the sub-agent / tool-call trace that produced it) is committed to scrollback so it stays visible in your history.

What iCli can do

iCli connects to the same AI engine as the in-browser terminal:

• Fleet-wide checks — asks about all devices at once with parallel sub-agents
• Live device data — reads VLAN tables, ONU lists, optical power, ARP, PPPoE sessions
• Customer lookup — find customers by name, IP, MAC, username, or invoice
• Config audits — review running config and get concrete suggestions
• Web search — looks up vendor CLI docs when it needs to
• Streaming output — reasoning, thoughts, and multi-step plans all stream live as they form, with an animated working indicator and step-by-step server progress
• Reasoning on by default — the model's reasoning trace streams inline (toggle with Ctrl+T / /reasoning, or start with --no-reasoning)
• Rich rendering — Markdown tables, colored lists, headings, and code blocks; @-mentions are highlighted; long lists render as aligned tables
• Interactive prompts — when the AI needs a decision, it shows a selectable choice list (↑/↓, Enter) with an optional free-text answer (Tab)
• Plans & connect cards — proposed fixes stream in live as a reviewable plan (apply fix to confirm, or use the Apply/Explain/Cancel prompt); device connections show as a connect card
• Bot memory — /remember saves standing operator notes that are injected into every answer (/memory, /forget to manage)
• Backups in git — /backup archives config to a per-user git repo; run /git status|log|commit|push from the prompt
• Share as a gist — /gist publishes the last answer or transcript to a secret GitHub gist
• Copy & paste — /copy puts the last answer on the clipboard; multi-line pastes (mouse right-click or Cmd/Ctrl+V) keep their line breaks, and Ctrl+Z / Ctrl+Y undo/redo work in the input
• Full-screen terminal UI — a full-height alternate-screen TUI with a home tab bar, blinking mascot, a bottom-pinned bordered input, a selectable slash-command menu, input history, mouse support (click to expand rows, drag the scrollbar, click to position the cursor), and a bottom-anchored transcript — the same layout as GitHub Copilot CLI 1.0.70. Piped/non-interactive use falls back to plain streaming output
• Terminal-aware rendering — the layout reflows to your terminal width and resizes live; on classic Windows consoles (cmd.exe / legacy PowerShell) it auto-switches to ASCII-safe glyphs and borders so nothing shows as broken boxes

API endpoints (for integrators)

iCli uses two endpoints added to your IspBills instance:

| Method | URL | Description | |---|---|---| | POST | /api/v1/auth/login | Get Bearer token (username + password) | | POST | /api/v1/ai/chat | Non-streaming JSON response | | POST | /api/v1/ai/chat/stream | SSE stream (delta / reason_delta / status_delta / done events) |

Authentication: Authorization: Bearer <token> on all /api/v1/ai/* requests.

Request body:

{
  "messages": [
    { "role": "user", "content": "is vlan 82 in use?" }
  ],
  "context": {
    "vendor": "auto",
    "connected": false
  }
}

SSE events:

data: {"delta": "VLAN 82 is..."}        ← streaming answer tokens
data: {"reason_delta": "checking..."}   ← AI reasoning (dim, italic)
data: {"status_delta": "✅ [1/3]..."}   ← sub-agent progress
data: {"done": true, "result": {...}}   ← final result object

Configuration

Config is stored at ~/.config/ispbills-icli/config.json:

{
  "url": "https://app.myisp.com",
  "token": "...",
  "refresh_token": "...",
  "user": { "id": 1, "name": "Admin", "email": "[email protected]", "role": "group_admin" }
}

Tokens refresh automatically when they expire.

License

MIT — © IspBills