@airsoko/cli

Official command-line tool for building on the Airsoko platform. Scaffold partner apps and storefront themes with the conventions, dependencies, and configuration needed to connect to Merchant Admin and MAPI.

Requirements

• Node.js 18 or later
• npm (used for installing scaffolded projects)

Installation

npm install -g @airsoko/cli

Or run without a global install:

npx @airsoko/cli app init
npx create-airsoko-app my-app

Quick start

Create a partner app, register it in the partner dashboard, then run it locally:

npm install -g @airsoko/cli   # or: npx @airsoko/cli app init
mkdir my-partner-app && cd my-partner-app
airsoko app init my-partner-app -y --install

1. Register the app in the partner dashboard (handle, app URL, OAuth redirect).
2. Set MACIVE_APP_CLIENT_ID, MACIVE_APP_CLIENT_SECRET, and MACIVE_APP_ID in .env.local.
3. Start development:

airsoko app dev

Register this OAuth redirect URI (replace <port> with your dev port, default 3011):

http://localhost:<port>/api/oauth/callback

The generated project includes a setup guide in docs/APP.md.

Full partner development guide (deploy, scenarios, theme zip upload): MAPI repo docs/app-platform/development-guide.md (local: /var/www/html/mapi/docs/app-platform/development-guide.md).

Commands

Authentication

Sign in through accounts.airsoko.com (platform OAuth + PKCE). Tokens are saved to ~/.airsoko/credentials.json and used automatically by theme commands when your project .env does not override them.

| Command | Description | |---------|-------------| | airsoko auth login | Interactive picker (Partner default, Shop, or Both) | | airsoko auth login partner | Partner token → AIRSOKO_PARTNER_TOKEN (theme push) | | airsoko auth login shop | Shop token + shop id → AIRSOKO_SHOP_TOKEN, AIRSOKO_SHOP_ID (theme push --live) | | airsoko auth login all | Partner then shop in one session | | airsoko auth status | Show saved credentials | | airsoko auth logout [kind] | Clear partner, shop, or all |

# From a theme directory — also writes ~/.airsoko/credentials.json into .env
airsoko auth login partner -d .
airsoko auth login shop -d .
airsoko theme push --bump --live

Use --no-open to print the authorize URL without launching a browser. Default callback: http://127.0.0.1:8976/callback.

Partner apps

| Command | Description | |---------|-------------| | airsoko app init [name] | Create a new partner app | | airsoko app dev | Start the Next.js dev server | | airsoko app build | Production build | | airsoko app start | Run the production server |

create-airsoko-app [name] is an alias for airsoko app init.

app init options

| Flag | Description | |------|-------------| | -d, --directory <path> | Output directory — use . for cwd (default when [name] is passed) | | -t, --title <title> | App title in Merchant Admin | | --handle <handle> | Partner dashboard slug | | -p, --port <port> | Dev server port (default 3011) | | --mapi <url> | MAPI base URL | | --admin <url> | Merchant admin origin | | --marketplace <url> | Marketplace origin | | --install | Run npm install after scaffolding (default: off — files only) | | --skip-install | Skip npm install (default; same as omitting --install) | | -y, --yes | Non-interactive mode (requires app name) |

# Interactive — pre-filled dev settings; scaffolds into cwd by default
airsoko app init

# Non-interactive — files only (no npm install)
airsoko app init my-app -y

# Non-interactive — scaffold and install dependencies
airsoko app init my-app -y --install

Pre-filled defaults (third-party devs can press Enter through most prompts):

| Setting | Default | |---------|---------| | Directory | Current folder (.) | | Handle | Same as app name | | Port | 3011 | | MAPI | https://api.airsoko.com | | Admin | https://admin.airsoko.com | | Marketplace | https://marketplace.airsoko.com | | App URL (local dev) | http://localhost:3011 |

After project files are created, the CLI asks whether to install dependencies or continue without installing. Default selection is continue (files only). Pass --install or --skip-install to skip that prompt.

Storefront themes

| Command | Description | |---------|-------------| | airsoko theme init [name] | Scaffold a storefront theme |

airsoko theme init my-theme
cd my-theme && npm run validate

Generated themes include a customization guide in docs/THEME.md.

Theme env (.env in theme directory)

| Variable | Purpose | |----------|---------| | AIRSOKO_API_BASE | MAPI URL (e.g. https://api.airsoko.com or http://localhost:8000) | | AIRSOKO_PARTNER_TOKEN | Partner session token — Partner dashboard → Themes → CLI credentials card, or loginPartner GraphQL (docs) | | STOREFRONT_SHOP_HANDLE | Shop handle for airsoko theme dev preview |

cp .env.example .env
# Fill AIRSOKO_PARTNER_TOKEN, then:
airsoko theme push

What you get

Partner app scaffolds include:

• Next.js (App Router) project structure
• @airsoko/partner-app SDK — GraphQL, OAuth, webhooks, embedded admin bridge
• @macive/ui — admin-aligned UI components
• Authentication, installation storage, and environment configuration
• Sample pages and install flow (/install, /install/connect)

Theme scaffolds include Liquid-style templates, theme.json, sections, assets, and validation scripts.

Getting AIRSOKO_PARTNER_TOKEN

Used by airsoko theme push (Partner GraphQL uploadPartnerTheme). This is your partner account session token — not a shop/app token.

Easiest: CLI browser login

airsoko auth login partner -d .
# Or partner + shop for --live publish:
airsoko auth login all -d .

You will be redirected to accounts.airsoko.com to sign in and approve access. Tokens are stored in ~/.airsoko/credentials.json.

Partner dashboard

1. Log in to the Partner dashboard.
2. Open Themes.
3. Copy AIRSOKO_PARTNER_TOKEN from the CLI credentials card (or the full .env snippet).

Alternative: loginPartner mutation

curl -s -X POST "$MAPI_URL/graphql/partner/2025-04" \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation($e:String!,$p:String!){loginPartner(email:$e,password:$p){accessToken}}","variables":{"e":"[email protected]","p":"secret"}}' \
  | jq -r '.data.loginPartner.accessToken'

Put the result in your theme .env as AIRSOKO_PARTNER_TOKEN.

Full guide: MAPI docs/partner-cli-token.md.

Related packages

• @airsoko/partner-app — Partner app runtime SDK
• @macive/ui — Admin design system
• @airsoko/oauth-client — Customer OAuth client

License

MIT