zii-cli

CLI and MCP server for zii.one — link shortener with QR codes, share thumbnails, and analytics.

• zii — terminal CLI (npm-publishable)
• zii-mcp — MCP stdio server for Claude Code / Claude Desktop / any MCP client
• claude/skills/zii/ — companion Claude skill (drop into a plugin marketplace)

Install

npm i -g zii-cli
# or use without installing
npx zii-cli@latest --help

Authenticate

Get an API key from your zii.one account → API Keys, then:

zii login <api-key>          # writes ~/.config/zii/config.json (mode 0600)
# or
export ZII_API_KEY=<api-key>

Verify:

zii doctor

Resolution order (first hit wins): --api-key flag → ZII_API_KEY env → ./.env → ~/.config/zii/config.json (XDG) → ./.ziirc.json / ./zii.config.json.

Quick CLI examples

# Shorten
zii shorten https://example.com/some/long/path --name "Launch post"
zii shorten https://example.com --path my-slug --json

# Update / delete
zii update <id> --destination https://new.example.com
zii delete <id>

# Preview Open Graph metadata for any URL
zii metadata https://example.com

# Render share thumbnails (30–120s)
zii thumbnail <linkId> --force

# Analytics
zii analytics summary <linkId>
zii analytics clicks-by-dates <linkId> --start-date 2025-01-01 --end-date 2025-01-31
zii analytics countries <linkId>
zii analytics referrers <linkId>

# API keys
zii api-key list
zii api-key create --name ci
zii api-key delete <id>

Every command supports --json. Exit codes: 0 ok, 1 user error, 2 auth, 3 network, 4 runtime/5xx.

MCP server

Run as a stdio MCP server:

ZII_API_KEY=<key> zii-mcp

Wire into Claude Desktop / Claude Code:

{
  "mcpServers": {
    "zii": {
      "command": "npx",
      "args": ["-y", "zii-cli", "zii-mcp"],
      "env": { "ZII_API_KEY": "<your-key>" }
    }
  }
}

Tools exposed (read-only marked R, mutating marked M):

| Tool | Mode | Purpose | |------|------|---------| | zii_health | R | Connectivity probe | | zii_scrape_metadata | R | Preview OG metadata for a URL | | zii_get_analytics_summary | R | Overview of clicks / scans / geo | | zii_get_analytics_by_dimension | R | Drill into one slice | | zii_list_api_keys | R | List user's keys | | zii_shorten_link | M | Create short link | | zii_update_link | M | Patch link fields | | zii_delete_link | M | Delete link (irreversible) | | zii_generate_thumbnail | M | Render share thumbnails (slow) | | zii_create_api_key | M | Issue new key (secret returned once) | | zii_delete_api_key | M | Revoke key (irreversible) |

Programmatic use

import { ZiiClient } from "zii-cli";

const zii = new ZiiClient({ apiKey: process.env.ZII_API_KEY! });
const link = await zii.createLink({ destinationUrl: "https://example.com" });
console.log(link.id);

Repo layout

src/
├── core/    # transport-agnostic API client (no CLI/MCP deps)
├── cli/     # commander-based CLI
└── mcp/     # MCP stdio server
claude/skills/zii/   # companion skill (SKILL.md + plugin.json)
test/                # vitest suite

Development

npm install
npm run build
npm test

License

MIT © Goon Nguyen