GISIS CLI

Authoritative IMO ship particulars on the command line, plus a local cache that turns one-shot lookups into a compounding vessel index.

GISIS is the IMO's canonical ship registry, gated by a login + Cloudflare Turnstile and only readable from a server-rendered web app. This CLI scrapes it politely (1 req/2-3s), caches every result to local SQLite, exposes 'ship get' as an MCP tool, and adds maritime-DD-specific commands like 'ship history' for flag-hop detection and 'owner fleet' for counterparty exposure that the GISIS web app itself can't answer.

Learn more at GISIS.

Created by @6myfzqx6bv-ctrl (ivory_elephant). Contributors: @tmchow (Trevin Chow).

Authentication

GISIS requires a free IMO Web Accounts login (https://webaccounts.imo.org/Register.aspx?App=GISISPublic) with a Cloudflare Turnstile challenge. Programmatic login is blocked, so this CLI uses the press-auth companion: install it once, run 'press-auth login gisis.imo.org', a controlled Chrome window opens for you to sign in, and your cookies are captured into the macOS keychain. The CLI then reads cookies on demand. Sessions die after ~30 min of inactivity; run 'gisis-pp-cli auth ping' from cron to keep them warm, or re-run 'press-auth login' when the session expires.

Quick Start

# Health check first — confirms binary works without making network calls.
gisis-pp-cli doctor --dry-run

# Install the cookie companion (one-time).
go install github.com/mvanhorn/cli-printing-press/v4/cmd/press-auth@latest

# Capture your GISIS session cookies via a controlled Chrome window.
press-auth login gisis.imo.org --login-url https://webaccounts.imo.org/Login.aspx?App=GISISPublic --jwt-carrier-cookie ASP.NET_SessionId

# Verify auth — should report cookies present and session live.
gisis-pp-cli doctor --json

# Fetch authoritative ship particulars by IMO number.
gisis-pp-cli ship get 9966233 --json

# Browse your accumulating local cache.
gisis-pp-cli ship list --json

Unique Features

These capabilities aren't available in any other tool for this API.

Local state that compounds

• ship batch — Resolve a list of IMOs in one invocation, honoring the 1 req/2-3s throttle and persisting each to the local cache.

  When an agent needs particulars for many vessels, this is the polite + persistent path. Single IMO? Use 'ship get'.

  gisis-pp-cli ship batch --imos 9966233,9123456 --json
  

• ship list — Browse vessels you have already fetched, with filters on flag/owner/type and full-text search on name/owner.

  When you want to find a vessel you saw before, this beats re-fetching from GISIS.

  gisis-pp-cli ship list --owner "ACME" --type Tanker --json
  

• ship pin — Pin vessels for an active deal or story, then refresh only the pinned ones at a chosen cadence.

  Use this to keep a working set of vessels current without re-fetching the whole cache.

  gisis-pp-cli ship pin 9966233 --label deal-2026-Q2 && gisis-pp-cli ship refresh --pinned --older-than 30d
  

• ship stale — List cached vessels whose particulars haven't been refreshed in N days.

  Compliance recency: when you need to know which dossier vessels need re-checking.

  gisis-pp-cli ship stale --older-than 30d --pinned --json
  

Maritime due-diligence signals

• ship history — Show how a vessel's particulars have changed across snapshots — flag, name, owner, operator, classification society, status.

  Flag-hopping and ownership changes are the textbook sanctions-bypass tells in maritime DD. Use this when you need temporal context, not a snapshot.

  gisis-pp-cli ship history 9966233 --json
  

• owner fleet — List every cached vessel for a given owner string (the Companies module isn't in v1).

  Counterparty exposure and related-vessel discovery without hitting the deferred Companies module.

  gisis-pp-cli owner fleet "ACME SHIPPING LTD" --like --json
  

Reachability mitigation

• auth ping — Single fast GET to /Public/SHIPS/Default.aspx; exits 0 if session is live, non-zero if re-login needed.

  Long batch jobs and unattended cron tasks need a cheap way to know if the session is still alive.

  gisis-pp-cli auth ping
  

Recipes

Look up an IMO with structured output

gisis-pp-cli ship get 9966233 --json --select name,flag,type,gross_tonnage,registered_owner

Returns the four high-gravity fields needed for a KYC entry.

Run a nightly batch over a watchlist

gisis-pp-cli ship batch --file ~/watchlist.txt --json | jq -c '.'

Resolves every IMO in the file under the throttle and streams JSON-lines.

Spot a flag change on a pinned vessel

gisis-pp-cli ship refresh --pinned --older-than 7d && gisis-pp-cli ship history 9966233 --json

Refresh stale pinned ships, then check the diff on one of them.

Find all cached ships under one owner

gisis-pp-cli owner fleet "COSCO SHIPPING" --like --json

Synthesizes counterparty exposure from accumulated lookups.

Keep the session alive from cron

*/20 * * * * /usr/local/bin/gisis-pp-cli auth ping >/dev/null 2>&1

ASP.NET sessions time out at ~30 min idle; ping every 20 to stay warm.

Usage

Run gisis-pp-cli --help for the full command reference and flag list.

Commands

ship

Ship particulars — authoritative IMO vessel registry data (name, flag, type, gross tonnage, ownership, classification society).

• gisis-pp-cli ship <IMONumber> - Get ship particulars by IMO number from the IMO Ship and Company Particulars module.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
gisis-pp-cli ship mock-value

# JSON for scripting and agents
gisis-pp-cli ship mock-value --json

# Filter to specific fields
gisis-pp-cli ship mock-value --json --select id,name,status

# Dry run — show the request without sending
gisis-pp-cli ship mock-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
gisis-pp-cli ship mock-value --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

gisis-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/gisis-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Troubleshooting

Authentication errors (exit code 4)

• Run gisis-pp-cli doctor to check credentials Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• doctor reports 'session expired' or 'login wall detected' — Re-run 'press-auth login gisis.imo.org' to capture fresh cookies.
• ship get returns 'WebLogin redirect' error — Same as above — session died. Re-run 'press-auth login gisis.imo.org'.
• press-auth login window times out without capturing — Add --complete-selector a[href*=Logoff] so press-auth knows when login is done.
• throttle warnings on batch lookups — Default throttle is 1 req/2-3s per the API's polite-use convention. Increase --delay if GISIS starts rate-limiting.

HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• equasis-cli — Python (17 stars)
• vesselapi-mcp — TypeScript

Generated by CLI Printing Press