invarn

Mobile CI (iOS / Android) from your terminal — with a built-in MCP server so AI agents (Claude Code, Cursor, Claude Desktop, Codex) can drive your builds, tests, and releases from inside a conversation.

Install

npm install -g @invarn/cli

This installs the invarn command.

Getting Started

1. Authenticate

invarn auth login                   # Browser-based (recommended)
invarn auth login --device-auth     # Device code (headless/SSH)
invarn auth login --token inv_human_...   # Direct token from the dashboard

2. Run a build

# Submit an iOS / Android build on Invarn's infrastructure
invarn build run --pipeline .ci/pipelines/cibuild.yml --workflow primary

# Or run a local pipeline on your own machine (via @invarn/cibuild)
invarn run --pipeline .ci/pipelines/agent-verify.yml --workflow test

3. Let AI drive your CI

Start the MCP server and your AI coding agent can register agents, run builds, and report results without leaving the conversation:

invarn mcp serve

Add it to Claude Code, Cursor, Claude Desktop, or Codex. If you installed @invarn/cli globally:

{
  "mcpServers": {
    "invarn": {
      "command": "invarn",
      "args": ["mcp", "serve"]
    }
  }
}

Or without a global install, using npx (pins a specific version for reproducibility):

{
  "mcpServers": {
    "invarn": {
      "command": "npx",
      "args": ["-y", "@invarn/cli@latest", "mcp", "serve"]
    }
  }
}

Commands

| Command | Description | |---|---| | invarn auth login | Authenticate via browser (PKCE) | | invarn auth login --device-auth | Authenticate via device code (headless) | | invarn auth login --token <token> | Authenticate with a token directly | | invarn auth logout | Remove stored credentials | | invarn auth status | Show current auth state | | invarn build run --pipeline <path> --workflow <name> | Submit a new proof | | invarn build list [--state <s>] | List recent proofs | | invarn build status <build-id> | Show proof details | | invarn build logs <build-id> | Stream proof logs | | invarn build cancel <build-id> | Cancel a running proof | | invarn build retry <build-id> | Retry a failed proof | | invarn artifact list <build-id> | List artifacts for a proof | | invarn artifact download <build-id> [--out <dir>] | Download artifact bundle | | invarn secrets list [--pipeline <id>] | List secrets at org or pipeline scope | | invarn secrets set <KEY> [--pipeline <id>] | Create or update a secret (stdin-only) | | invarn secrets rm <KEY> [--pipeline <id>] | Delete a secret | | invarn vars list/set/rm | Same as secrets for plaintext variables | | invarn run --pipeline <path> [--workflow <name>] | Run a local-* pipeline on this machine | | invarn mcp serve | Start MCP server for AI agents |

Options

| Flag | Description | |---|---| | --json | Output as JSON | | --no-follow | Don't follow logs (snapshot only) | | --out <dir> | Output directory for downloads |

Local pipelines

Pipelines with stack: local run on your own machine via the embedded @invarn/cibuild engine — no remote runner, no network round trip. Useful for fast iteration and for AI agents that need to verify changes before a push.

# .ci/pipelines/agent-verify.yml
format_version: '1'
meta:
  cibuild.io:
    stack: local
workflows:
  test:
    steps:
      - [email protected]:
          inputs:
            content: npm ci && npm test

invarn run --pipeline .ci/pipelines/agent-verify.yml --workflow test

MCP server (for AI agents)

invarn mcp serve exposes build, artifact, secret, and agent operations as MCP tools:

| Tool | Description | |---|---| | invarn_agent_find | Search for an existing agent by intent/type | | invarn_agent_register | Register a new AI agent with its own pipeline | | invarn_agent_list | List all agents in the organization | | invarn_agent_unregister | Delete an agent | | invarn_agent_run | Run a workflow through an agent (local or remote) | | invarn_agent_result | Fetch build state, step progress, logs, artifacts | | invarn_build_list | List recent builds | | invarn_build_logs | Fetch log output for a build | | invarn_build_cancel | Cancel a running build | | invarn_build_retry | Retry a failed build | | invarn_artifact_list | List artifacts for a build | | invarn_secrets_list | List secret/variable metadata (never values) | | invarn_secrets_set | Create or update a secret or variable |

Agents are AI-owned pipelines — created on demand by an orchestrator (Claude, Codex, Cursor, …), invoked by AI, and reported back into the conversation. Each agent has its own credentials, its own pipeline file, and short-lived session tokens scoped to one human user. Typical uses: compile the iOS/Android app, run unit tests, produce an IPA/APK, push a TestFlight build.

Secrets

Secrets and variables are scoped to the org or a specific pipeline. Values are piped via stdin — never passed on argv (visible in shell history and ps output):

echo "sk_live_..." | invarn secrets set STRIPE_KEY
echo "sk_live_..." | invarn secrets set STRIPE_KEY --pipeline pipe_abc
echo "sk_live_..." | invarn secrets set STRIPE_KEY --agent agt_xyz   # scope to the agent's owned pipeline
invarn secrets list
invarn secrets list --agent agt_xyz
invarn secrets rm STRIPE_KEY

--agent and --pipeline are mutually exclusive. The agent variant is a convenience — the server resolves the agent's 1:1 pipeline internally, so you don't need to look up the pipeline id in the dashboard. Same applies to the invarn_secrets_set / invarn_secrets_list MCP tools (pass agent_id).

There is no read command — once set, values cannot be retrieved through the CLI or MCP.

In-process SDK (for agent hosts)

If you're embedding Claude in your own Node application via @anthropic-ai/claude-agent-sdk, skip the subprocess and register invarn as an in-process MCP server instead:

import { query } from '@anthropic-ai/claude-agent-sdk'
import { createInvarnMcpServer } from '@invarn/cli/sdk'

const invarn = createInvarnMcpServer({
  token: process.env.INVARN_API_KEY,   // or INVARN_TOKEN env / disk profile
  tools: ['invarn_build_list', 'invarn_agent_run', 'invarn_agent_result'],
})

for await (const msg of query({
  prompt: 'Build the iOS app and report status.',
  options: {
    mcpServers: { invarn },
    allowedTools: [
      'mcp__invarn__invarn_build_list',
      'mcp__invarn__invarn_agent_run',
      'mcp__invarn__invarn_agent_result',
    ],
  },
})) { /* ... */ }

Options

| Option | Default | Notes | |---|---|---| | token | process.env.INVARN_TOKEN → disk profile | Invarn human API key (inv_human_...) | | baseUrl | process.env.INVARN_URL → https://invarn.com | Override for self-hosted deployments | | tools | all 13 | Allowlist by tool name. | | version | CLI version | Reported as the MCP server version |

Responses from the SDK path are JSON (JSON.stringify(result, null, 2) in a single text block), not the formatted prose the stdio CLI emits — LLMs parse structured data more reliably. The stdio server (invarn mcp serve) is unchanged.

The Agent SDK is a peer dependency; the consuming host resolves its version.

Requirements

• Node.js 22+
• A registered Invarn organization (sign up at invarn.com)
• An iOS or Android project connected to Invarn via GitHub