or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

asset-management.mdcli-commands.mdconfiguration.mdindex.mdplatform-operations.mdplugin-management.mdvalidation.md
tile.json

tessl/npm-capacitor--cli

Command-line interface for Capacitor cross-platform native runtime that enables building web apps for iOS, Android, and other platforms

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@capacitor/cli@7.4.x

To install, run

npx @tessl/cli install tessl/npm-capacitor--cli@7.4.0

index.mddocs/

Capacitor CLI

Capacitor CLI is the command-line interface for Capacitor, a cross-platform native runtime that enables building web apps that run natively on iOS, Android, and other platforms. The CLI serves as the primary development tool for creating, managing, and building Capacitor applications, offering comprehensive project management and native platform integration.

Package Information

  • Package Name: @capacitor/cli
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @capacitor/cli

Core Imports

The Capacitor CLI is primarily designed as a command-line tool. For programmatic usage, the main exports are:

import { run, runProgram, loadConfig, writeConfig } from "@capacitor/cli";

For CommonJS:

const { run, runProgram, loadConfig, writeConfig } = require("@capacitor/cli");

Primary CLI Binary Usage:

npx cap <command> [options]
# or
npx capacitor <command> [options]

Basic Usage

Programmatic Usage:

import { run, loadConfig } from "@capacitor/cli";

// Run the CLI programmatically (loads config and runs program)
await run();

// Or load config and access properties
const config = await loadConfig();
console.log(config.app.appId); // Your app ID
console.log(config.app.webDir); // Web assets directory

Command-line usage:

# Initialize Capacitor in an existing project
npx cap init "My App" com.example.myapp

# Add native platforms
npx cap add ios
npx cap add android

# Sync web assets and update native dependencies
npx cap sync

# Build and run on device
npx cap run ios
npx cap run android

Architecture

Capacitor CLI is built around several key components:

  • Configuration System: Centralized config loading and validation with TypeScript support
  • Platform Abstraction: Unified API for iOS, Android, and web platform operations
  • Plugin Management: Integration with Capacitor and Cordova plugin ecosystems
  • Asset Pipeline: Web asset copying and synchronization with native projects
  • Build Orchestration: Native build process management with signing and deployment
  • Development Tools: Live reload, debugging, and project scaffolding capabilities

Capabilities

Configuration Management

Load, validate, and manage Capacitor project configurations with full TypeScript support.

/**
 * Load Capacitor configuration from the current working directory
 */
function loadConfig(): Promise<Config>;

/**
 * Write Capacitor configuration to a file
 * @param extConfig - External configuration object to write
 * @param extConfigFilePath - Path to the configuration file
 */
function writeConfig(extConfig: ExternalConfig, extConfigFilePath: string): Promise<void>;

interface Config {
  readonly android: AndroidConfig;
  readonly ios: IOSConfig;
  readonly web: WebConfig;
  readonly cli: CLIConfig;
  readonly app: AppConfig;
  readonly plugins?: PluginsConfig;
}

Configuration

CLI Commands

Complete command-line interface for Capacitor project management and development.

/**
 * Main CLI entry point - loads config and runs the program
 */
function run(): Promise<void>;

/**
 * Configures and runs the CLI program with provided config
 * @param config - Loaded Capacitor configuration
 */
function runProgram(config: Config): void;

Available commands: init, sync, update, copy, build, run, open, add, ls, doctor, migrate, and more.

CLI Commands

Platform Operations

Cross-platform operations for adding, building, and managing iOS and Android projects are available through CLI commands. Platform-specific operations are handled internally and are not exposed as exportable functions.

Platform Operations

Plugin Management

Comprehensive plugin discovery, installation, and management for Capacitor and Cordova plugins.

function getPlugins(config: Config): Promise<Plugin[]>;

interface Plugin {
  id: string;
  name: string;
  version: string;
  rootPath: string;
  manifest?: PluginManifest;
  ios?: {
    name: string;
    type: PluginType;
    path: string;
  };
  android?: {
    type: PluginType;
    path: string;
  };
}

Plugin Management

Asset Management

Web asset copying and synchronization between web and native projects.

function copy(config: Config, platformName: string, inline?: boolean): Promise<void>;
function sync(config: Config, platformName: string, deployment: boolean, inline?: boolean): Promise<void>;

Asset Management

Validation and Diagnostics

Comprehensive validation tools and diagnostics for project setup and configuration.

type CheckFunction = () => Promise<string | null>;

function check(checks: CheckFunction[]): Promise<void>;
function checkWebDir(config: Config): Promise<string | null>;
function checkAppConfig(config: Config): Promise<string | null>;
function doctorCommand(config: Config, platform?: string): Promise<void>;

Validation

Core Types

Exported Types and Interfaces:

// Configuration Types
type ExternalConfig = DeepReadonly<CapacitorConfig>;

interface Config {
  readonly android: AndroidConfig;
  readonly ios: IOSConfig;
  readonly web: WebConfig;
  readonly cli: CLIConfig;
  readonly app: AppConfig;
  readonly plugins?: PluginsConfig;
}

interface AppConfig {
  readonly rootDir: string;
  readonly appId: string;
  readonly appName: string;
  readonly webDir: string;
  readonly webDirAbs: string;
  readonly package: PackageJson;
  readonly extConfigType: 'json' | 'js' | 'ts';
  readonly extConfigName: string;
  readonly extConfigFilePath: string;
  readonly extConfig: ExternalConfig;
}

interface AndroidConfig extends PlatformConfig {
  readonly cordovaPluginsDir: string;
  readonly cordovaPluginsDirAbs: string;
  readonly studioPath: Promise<string>;
  readonly minVersion: string;
  readonly appDir: string;
  readonly appDirAbs: string;
  readonly srcDir: string;
  readonly srcDirAbs: string;
  readonly srcMainDir: string;
  readonly srcMainDirAbs: string;
  readonly webDir: string;
  readonly webDirAbs: string;
  readonly assetsDir: string;
  readonly assetsDirAbs: string;
  readonly resDir: string;
  readonly resDirAbs: string;
  readonly buildOutputDir: string;
  readonly buildOutputDirAbs: string; // Deprecated
  readonly apkName: string; // Deprecated
  readonly flavor: string;
  readonly buildOptions: {
    keystorePath?: string;
    keystorePassword?: string;
    keystoreAlias?: string;
    keystoreAliasPassword?: string;
    releaseType?: 'AAB' | 'APK';
    signingType?: 'apksigner' | 'jarsigner';
  };
}

interface IOSConfig extends PlatformConfig {
  readonly cordovaPluginsDir: string;
  readonly cordovaPluginsDirAbs: string;
  readonly minVersion: string;
  readonly podPath: Promise<string>;
  readonly scheme: string;
  readonly webDir: Promise<string>;
  readonly webDirAbs: Promise<string>;
  readonly nativeProjectDir: string;
  readonly nativeProjectDirAbs: string;
  readonly nativeTargetDir: string;
  readonly nativeTargetDirAbs: string;
  readonly nativeXcodeProjDir: string;
  readonly nativeXcodeProjDirAbs: string;
  readonly nativeXcodeWorkspaceDir: Promise<string>;
  readonly nativeXcodeWorkspaceDirAbs: Promise<string>;
  readonly buildOptions: {
    teamId?: string;
    exportMethod?: XcodeExportMethod;
    xcodeSigningStyle?: 'automatic' | 'manual';
    signingCertificate?: string;
    provisioningProfile?: string;
  };
}

interface CLIConfig {
  readonly rootDir: string;
  readonly assetsDir: string;
  readonly assetsDirAbs: string;
  readonly assets: {
    readonly ios: PlatformAssetsConfig;
    readonly android: PlatformAssetsConfig;
  };
  readonly package: PackageJson;
  readonly os: OS;
}

interface PlatformConfig {
  readonly name: string;
  readonly platformDir: string;
  readonly platformDirAbs: string;
}

interface PlatformAssetsConfig {
  readonly platformTemplateArchive: string;
  readonly platformTemplateArchiveAbs: string;
  readonly cordovaPluginsTemplateArchive: string;
  readonly cordovaPluginsTemplateArchiveAbs: string;
}

interface PackageJson {
  readonly name: string;
  readonly version: string;
  readonly dependencies?: { readonly [key: string]: string | undefined };
  readonly devDependencies?: { readonly [key: string]: string | undefined };
}

type WebConfig = PlatformConfig;

// Enums
enum OS {
  Unknown = 'unknown',
  Mac = 'mac',
  Windows = 'windows',
  Linux = 'linux'
}

enum XcodeExportMethod {
  AppStoreConnect = 'app-store-connect',
  ReleaseTesting = 'release-testing',
  Enterprise = 'enterprise',
  Debugging = 'debugging',
  DeveloperID = 'developer-id',
  MacApplication = 'mac-application',
  Validation = 'validation'
}

// Capacitor Configuration Interface (from @capacitor/cli)
interface CapacitorConfig {
  appId?: string;
  appName?: string;
  webDir?: string;
  bundledWebRuntime?: boolean;
  // ... additional configuration options
}

interface PluginsConfig {
  [pluginName: string]: any;
}