Shipli Docs — Documentation

Installation

Install Shipli globally via npm. Requires Node.js 18+.

$ npm install -g @prasenjeet/shipli

Verify the installation:

        $ shipli --version

        1.1.0

Quick Start

Set up your AI provider and API key, then run your first audit:

        # Interactive setup — select provider, model, enter API key

        $ shipli init

        # Run the audit (auto-detects platform and project type)

        $ shipli --dir /path/to/flutter/project

Or pass everything inline without a config file:

$ shipli --dir ./ --provider claude --key YOUR_API_KEY

Commands

Command	Description
`shipli init`	Create a `.shipli` config file interactively (provider, model, API key)
`shipli config`	Update provider, model, or API key in an existing `.shipli`
`shipli --dir <path>`	Run the audit (default command)
`shipli --help`	Show all options

Options Reference

Flag	Description	Default
`--dir <path>`	Path to Flutter project root	required
`--key <key>`	API key	`.shipli` / env var
`--provider <name>`	`gemini` or `claude`	`gemini`
`--model <model>`	Model override	Per provider default
`--type <type>`	`app` or `package`	Auto-detected
`--mode <mode>`	`store`, `code`, or `both`	`both`
`--platform <platform>`	`ios`, `android`, or `both`	Auto-detected

Configuration File

Run shipli init to create a .shipli config file, or create one manually:

{

  "provider": "claude",

  "key": "sk-ant-...",

  "model": "claude-sonnet-4-6",

  "platform": "both",

  "mode": "both"

}

Resolution Order

Values are resolved in this order (highest priority wins):

CLI flags (--key, --provider, etc.)
Project-level .shipli (in the --dir path)
Global ~/.shipli (home directory)
Environment variables (GEMINI_API_KEY / ANTHROPIC_API_KEY)
Built-in defaults

Add .shipli to your .gitignore — it contains your API key.

Use shipli config to update settings anytime via interactive arrow-key menus.

Supported Models

Claude (Anthropic)

Model	Tier
`claude-sonnet-4-6`	Recommended — balanced flagship
`claude-opus-4-6`	Frontier — highest reasoning
`claude-haiku-4-5`	Fastest & cheapest
`claude-opus-4-5`	Frontier intelligence
`claude-sonnet-4-5`	Balanced — enterprise
`claude-opus-4-1`	Advanced reasoning
`claude-opus-4`	Advanced reasoning
`claude-sonnet-4`	Balanced
`claude-sonnet-3-7`	Legacy — balanced
`claude-haiku-3-5`	Legacy — fast
`claude-sonnet-3-5`	Legacy — balanced

Gemini (Google)

Model	Tier
`gemini-3.1-pro`	Frontier — advanced reasoning, 1M context
`gemini-3.1-flash-lite`	Ultra-efficient — lowest latency
`gemini-3-flash`	High-performance multimodal + coding
`gemini-2.5-flash`	Recommended — fast & cheap
`gemini-2.5-pro`	Strong reasoning + multimodal
`gemini-2.5-flash-lite`	Lightweight — high-volume
`gemini-1.5-pro`	Legacy — early multimodal
`gemini-1.5-flash`	Legacy — fast

Audit Modes

`--mode store`

Checks only store compliance: permissions, privacy, IAP, legal, content policy. Loads bundled Apple/Google guidelines as grounding context. Best for pre-submission checks.

$ shipli --dir ./ --mode store

`--mode code`

Checks only code quality: security, architecture, error handling, performance, best practices, dependencies. Skips guideline loading entirely.

$ shipli --dir ./ --mode code

`--mode both` (default)

Runs both store compliance and code quality checks in a single audit. Uses more tokens but gives the most comprehensive report.

$ shipli --dir ./

Platform Targeting

Shipli auto-detects the target platform by checking for ios/ and android/ directories. Override with --platform:

        # iOS App Store only

        $ shipli --dir ./ --platform ios

        # Google Play only

        $ shipli --dir ./ --platform android

        # Both stores

        $ shipli --dir ./ --platform both

Platform	Reads	Guidelines
`ios`	`Info.plist`	Apple App Store Review Guidelines
`android`	`AndroidManifest.xml`	Google Play Developer Policies
`both`	Both files	Both guidelines

Package Auditing

Shipli auto-detects Flutter packages/plugins from flutter: plugin: in pubspec.yaml. Package audits focus on:

API surface & documentation quality
Platform declarations (MethodChannel consistency)
Consumer permissions guidance
Dependency hygiene
Example app quality

If the package has an example/ directory, Shipli scans it too.

        # Force package mode

        $ shipli --dir ./my-plugin --type package

MCP Server

Shipli includes a built-in Model Context Protocol (MCP) server. AI coding assistants like Claude Code, Cursor, and Windsurf can run audits directly inside your editor.

Setup

Step 1 — Install Shipli globally

The shipli-mcp binary is included with the package.

$ npm install -g @prasenjeet/shipli

Verify both binaries are available:

$ shipli --version

$ which shipli-mcp

Step 2 — Add the MCP server

Option A: Claude Code CLI (recommended)

Run a single command to register the MCP server:

# Using Claude as the AI provider

$ claude mcp add shipli \

  --transport stdio \

  --env SHIPLI_PROVIDER=claude \

  --env SHIPLI_MODEL=claude-haiku-4-5 \

  --env ANTHROPIC_API_KEY=your-api-key \

  -- shipli-mcp

# Using Gemini as the AI provider

$ claude mcp add shipli \

  --transport stdio \

  --env SHIPLI_PROVIDER=gemini \

  --env SHIPLI_MODEL=gemini-2.5-flash \

  --env GEMINI_API_KEY=your-api-key \

  -- shipli-mcp

Option B: Manual JSON config

Add to ~/.claude/.mcp.json:

{

  "mcpServers": {

    "shipli": {

      "command": "shipli-mcp",

      "env": {

        "SHIPLI_PROVIDER": "claude",

        "SHIPLI_MODEL": "claude-haiku-4-5",

        "ANTHROPIC_API_KEY": "your-api-key"

      }

    }

  }

}

Cursor / Windsurf

Add the same JSON config to your editor's MCP settings. The command and env fields are identical.

Step 3 — Restart and verify

Restart Claude Code (or run /mcp in chat) to pick up the new server. You should see shipli listed with its two tools.

Environment Variables

Variable	Description	Required
`SHIPLI_PROVIDER`	`claude` or `gemini`	No (defaults to `gemini`)
`SHIPLI_MODEL`	Model override	No (uses provider default)
`ANTHROPIC_API_KEY`	API key for Claude	Yes, if provider is `claude`
`GEMINI_API_KEY`	API key for Gemini	Yes, if provider is `gemini`

MCP Tools

`shipli_store_audit`

Run a store compliance audit against Apple App Store and/or Google Play guidelines. Returns structured findings with PASS/WARNING/FAIL scores and specific guideline citations.

Parameter	Type	Required	Description
`projectDir`	string	Yes	Absolute path to the Flutter project root
`platform`	`ios` \| `android` \| `both`	No	Target platform. Auto-detected if omitted.

`shipli_code_review`

Run a code quality and security review. Checks architecture, error handling, performance, dependencies, and security vulnerabilities.

Parameter	Type	Required	Description
`projectDir`	string	Yes	Absolute path to the Flutter project root

Example Usage

Once configured, ask your AI assistant:

        # Store audit

        "Run a store audit on /path/to/my-flutter-app"

        # Code review

        "Review the code quality of this Flutter project"

        # iOS only

        "Audit my Flutter app for App Store compliance, iOS only"

The assistant calls the appropriate Shipli MCP tool and returns the results inline.

CI / CD Integration

Shipli exits with code 1 on FAIL and 0 on PASS/WARNING, making it easy to gate deployments.

GitHub Actions

name: Shipli Audit

on: [push]

jobs:

  audit:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: 20

      - run: npx @prasenjeet/shipli --dir ./ --provider claude --key ${{ '{{' }} secrets.ANTHROPIC_API_KEY {{ '}}' }}

Token Limits

Shipli estimates input token count before calling the AI and applies safety checks:

Provider	Context Window	Safe Input Limit
Claude	200K tokens	~150K (50K reserved for output)
Gemini	1M tokens	~900K (100K reserved for output)

At 80% of the limit, you'll see a yellow warning. Above 100%, Shipli stops with an error and suggests narrowing scope:

        # Reduce tokens by targeting one platform

        $ shipli --dir ./ --platform ios

        # Or one mode

        $ shipli --dir ./ --mode store

Telemetry

Shipli collects anonymous usage metrics to help improve the tool. No project data, file contents, API keys, or personally identifiable information is ever collected.

What's collected

Audit mode, platform, provider, model, pass/fail score, duration, token counts, OS, and CLI version.

What's NOT collected

Project paths, file names, or file contents
API keys or credentials
pubspec.yaml data or project names
Error stack traces

Opt out

Disable telemetry using any of these methods:

        # Environment variable

        $ export SHIPLI_TELEMETRY=off

        # Or use the Do Not Track standard

        $ export DO_NOT_TRACK=1

Or add "telemetry": false to your ~/.shipli config file.