ipaShip Docs — Complete CLI Reference, Configuration, CI/CD & MCP Setup

Installation

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

$ npm install -g @async-atharv/ipaship

Verify the installation:

$ ipaShip --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

$ ipaShip init

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

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

Or pass everything inline without a config file:

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

Commands

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

Options Reference

Flag	Description	Default
`--dir <path>`	Path to Flutter project root	required
`--key <key>`	API key	`.ipaShip` / 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 ipaShip init to create a .ipaShip 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 .ipaShip (in the --dir path)
Global ~/.ipaShip (home directory)
Environment variables (GEMINI_API_KEY / ANTHROPIC_API_KEY)
Built-in defaults

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

Use ipaShip 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.

$ ipaShip --dir ./ --mode store

`--mode code`

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

$ ipaShip --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.

$ ipaShip --dir ./

Platform Targeting

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

# iOS App Store only

$ ipaShip --dir ./ --platform ios

# Google Play only

$ ipaShip --dir ./ --platform android

# Both stores

$ ipaShip --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

ipaShip 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, ipaShip scans it too.

# Force package mode

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

MCP Server

ipaShip 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 ipaShip globally

The ipaShip-mcp binary is included with the package.

$ npm install -g @async-atharv/ipaship

Verify both binaries are available:

$ ipaShip --version
$ which ipaShip-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 ipaShip \

  --transport stdio \

  --env IPASHIP_PROVIDER=claude \

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

  --env ANTHROPIC_API_KEY=your-api-key \

  -- ipaShip-mcp

# Using Gemini as the AI provider

$ claude mcp add ipaShip \

  --transport stdio \

  --env IPASHIP_PROVIDER=gemini \

  --env IPASHIP_MODEL=gemini-2.5-flash \

  --env GEMINI_API_KEY=your-api-key \

  -- ipaShip-mcp

Option B: Manual JSON config

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

{

  "mcpServers": {

    "ipaShip": {

      "command": "ipaShip-mcp",

      "env": {

        "IPASHIP_PROVIDER": "claude",

        "IPASHIP_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 ipaShip listed with its two tools.

Environment Variables

Variable	Description	Required
`IPASHIP_PROVIDER`	`claude` or `gemini`	No (defaults to `gemini`)
`IPASHIP_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

`ipaShip_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.

`ipaShip_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 ipaShip MCP tool and returns the results inline.

CI / CD Integration

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

GitHub Actions

name: ipaShip 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 @async-atharv/ipaship --dir ./ --provider claude --key ${{ '{{' }} secrets.ANTHROPIC_API_KEY {{ '}}' }}

Token Limits

ipaShip 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%, ipaShip stops with an error and suggests narrowing scope:

# Reduce tokens by targeting one platform

$ ipaShip --dir ./ --platform ios

# Or one mode

$ ipaShip --dir ./ --mode store