Baseportal Developer CLI (base-dev)

CLI tool for developing and publishing Baseportal microfrontend apps.

🚀 Installation

npm install -g @baseportal/base-dev-cli
# or
pnpm add -g @baseportal/base-dev-cli

🔑 Authentication

The CLI always talks to the Baseportal API at https://api.baseportal.io.

The first time you run a command that needs the API (init, publish, promote, rollback, env pull), you'll be prompted for your API token. The token is saved to a .env file in the app root as SECRET_TOKEN and reused automatically on subsequent runs — .env is added to .gitignore so the token is never committed.

# .env (created automatically in the app root)
SECRET_TOKEN=your_token_here

To rotate the token, edit SECRET_TOKEN in .env (or delete the file to be prompted again). You can generate a token in Baseportal: Setup > Apps > Developer Token.

📝 Commands

base-dev init

Initialize a new Baseportal app. This command will:

• Prompt you for app details (namespace, name, description, etc.)
• Register the app with Baseportal API
• Create the project structure
• Generate manifest.json

base-dev init

Generated structure:

my-app/
├── manifest.json
├── frontend/
│   └── src/
│       └── App.tsx
├── backend/
│   └── functions/
│       └── index.ts
└── dist/

base-dev build

Build and package your app for publishing.

base-dev build

What it does:

• Validates manifest.json
• Packages frontend (dist/) and backend (backend/) into a .zip file
• Generates package hash for integrity verification
• Creates {namespace}-{version}.zip in the current directory

Prerequisites:

• Build your frontend first (e.g., npm run build)
• Ensure dist/ folder exists with built assets

base-dev publish

Publish your app to Baseportal.

base-dev publish

What it does:

• Creates a new version in the Baseportal registry
• Uploads the package (.zip file)
• Registers the package with integrity hash
• Returns version details and CDN URLs

Status flow:

• Initial status: draft
• Ready for review: in_review
• Production ready: approved

base-dev promote

Promote a version to a new status.

# Interactive mode
base-dev promote

# With options
base-dev promote --status approved
base-dev promote --status in_review --version 1.0.0

Options:

• -s, --status <status> - Target status: draft, in_review, approved, or deprecated
• -v, --version <version> - Version to promote (optional, will prompt if not provided)

Status meanings:

• draft - Work in progress, not published
• in_review - Submitted for review
• approved - Production ready, will be served to users
• deprecated - No longer recommended

base-dev rollback

Rollback to the previous approved version.

# Interactive mode
base-dev rollback

# With options
base-dev rollback --version 2.0.0

What it does:

• Marks the current version as deprecated
• Activates the previous approved version
• Updates the app's latest_version_id

📋 manifest.json

The manifest.json file defines your app's metadata and configuration.

Example:

{
  "name": "My App",
  "version": "1.0.0",
  "namespace": "my-app",
  "appId": "uuid-here",
  "description": "My awesome Baseportal app",
  "icon": "🚀",
  "type": "external",
  "entryPoint": "./dist/remoteEntry.js",
  "routes": [
    {
      "path": "/dashboard",
      "component": "Dashboard"
    }
  ],
  "permissions": [
    "read:users",
    "write:data"
  ],
  "dependencies": {
    "react": "^18.0.0"
  }
}

Required fields:

• name - App display name
• version - Semantic version (e.g., "1.0.0")
• namespace - Unique identifier (lowercase, no spaces)
• type - App type: system or external
• entryPoint - Path to main bundle (usually remoteEntry.js)

🔄 Workflow

Complete workflow for developing and publishing an app:

# 1. Initialize new app
base-dev init

# 2. Develop your app
cd my-app
npm install
npm run dev

# 3. Build your app
npm run build

# 4. Package for publishing
base-dev build

# 5. Publish to Baseportal
base-dev publish

# 6. Submit for review
base-dev promote --status in_review

# 7. Approve for production (after testing)
base-dev promote --status approved

# 8. If something goes wrong, rollback
base-dev rollback

🛠️ Development

To develop the CLI locally:

# Install dependencies
pnpm install

# Build TypeScript
pnpm run build

# Run locally
node dist/index.js init

# Or link globally
npm link
base-dev init

🐛 Troubleshooting

Authentication / invalid token

The CLI prompts for your token on first use and stores it in .env as SECRET_TOKEN. If the token is wrong or expired, edit .env (or delete it to be prompted again).

"Package not found"

Run base-dev build before base-dev publish.

"Version already exists"

Update the version number in manifest.json and rebuild.

"dist/ folder not found"

Build your frontend first (e.g., npm run build, vite build, etc.)

📚 API Endpoints Used

The CLI interacts with these Baseportal API endpoints:

• POST /panel/apps - Create app
• GET /panel/apps - List apps
• POST /panel/apps/:appId/versions - Create version
• GET /panel/apps/:appId/versions - List versions
• POST /panel/apps/:appId/versions/:versionId/publish - Upload package
• POST /panel/apps/:appId/versions/:versionId/promote - Promote version
• POST /panel/apps/:appId/versions/:versionId/rollback - Rollback version

📄 License

MIT

🤝 Support

For issues and questions:

• GitHub Issues: https://github.com/baseportal/base-dev-cli/issues
• Documentation: https://docs.baseportal.com