@camunda/teams-app-integration-cli

CLI tool for building and deploying Microsoft Teams app integrations with Camunda.

c8teams scaffolds a new Teams application project, builds the deployable package from templates, provisions it to your Microsoft 365 tenant via the M365 Agents Toolkit, and outputs the configuration snippet needed by the App Integrations backend.

Prerequisites

• Node.js ≥ 20.0.0
• A Microsoft 365 tenant with access for app provisioning

Installation

npm install -g @camunda/teams-app-integration-cli

Or use it as a project-local dependency:

npm install @camunda/teams-app-integration-cli

Quick Start

# 1. Scaffold a new project
c8teams create my-teams-app

# 2. Install dependencies
cd my-teams-app
npm install

# 3. Build the deployable package
npm run build

# 4. Deploy to your Microsoft 365 tenant
npm run deploy

Commands

c8teams create [DIRECTORY]

Scaffolds a new Camunda Teams application project via an interactive wizard.

The wizard will prompt you for:

• Project directory and package name
• Application short name and full name (displayed in Teams)
• App Integrations backend URL
• User registration URL (optional)
• Teams app configuration — create a new one or provide existing IDs
• Entra (Azure AD) app configuration — create a new one or provide existing IDs

The result is a directory containing a package.json with a c8teams configuration section, default app icon assets, and a .gitignore.

c8teams create
c8teams create my-teams-app

c8teams build

Builds the deployable package from the project's template files and configuration.

Reads the c8teams section from package.json, validates it against the config schema, renders the M365 Agents Toolkit manifest templates (Teams manifest, AAD manifest, agent config), copies app icon assets, and writes everything to a build/ directory.

After a successful build you will be prompted to deploy immediately.

| Option | Description | | ----------------- | -------------------------------------------------------- | | -p, --path PATH | Root path of the project (defaults to current directory) |

c8teams build
c8teams build -p ./my-teams-app

c8teams deploy

Deploys the built package to your Microsoft 365 tenant.

Runs atk provision --env prod inside the build/ directory using the M365 Agents Toolkit CLI bundled with this package (no global installation required). After provisioning, the command writes the resulting Teams and Entra IDs back into package.json and prints the backend configuration snippet.

| Option | Description | | ----------------- | -------------------------------------------------------------------- | | -p, --path PATH | Root path of the project (defaults to current directory) | | --auth | Authenticate with M365 before deploying (runs atk auth login m365) |

c8teams deploy
c8teams deploy --auth
c8teams deploy -p ./my-teams-app

Note: You must run c8teams build before deploying. The deploy command expects the build/ directory to exist.

c8teams show-config

Displays the YAML configuration snippet to add to your App Integrations backend, along with the client secret that must be mounted as the AAD_APP_CLIENT_SECRET environment variable.

| Option | Description | | ----------------- | -------------------------------------------------------- | | -p, --path PATH | Root path of the project (defaults to current directory) |

c8teams show-config
c8teams show-config -p ./my-teams-app

Global Options

| Option | Description | | --------------- | ----------------------------------------------------------------------------------- | | -h, --help | Show help. Use with a command (e.g. c8teams deploy -h) for command-specific help. | | -v, --version | Show the CLI version number |

Project Structure

After running create and build, your project will look like this:

my-teams-app/
├── assets/
│   ├── color.png          # App icon (color version)
│   └── outline.png        # App icon (outline version)
├── build/                  # Generated by `c8teams build`
│   ├── env/
│   │   └── .env.prod
│   ├── aad.manifest.json
│   ├── m365agents.yml
│   ├── manifest.json
│   ├── color.png
│   └── outline.png
├── .gitignore
└── package.json            # Contains the `c8teams` configuration section

Configuration

All configuration lives in the c8teams section of package.json. It is populated by the create wizard and updated automatically by deploy after provisioning.

{
  "c8teams": {
    "app": {
      "shortName": "Camunda",
      "fullName": "Camunda",
      "projectId": "<uuid>"
    },
    "endpoints": {
      "appIntegrationsBackend": "https://your-backend.example.com",
      "userRegistration": "https://signup.example.com"
    },
    "teams": {
      "appId": "<uuid>",
      "tenantId": "<uuid>"
    },
    "aad": {
      "clientId": "<uuid>",
      "objectId": "<uuid>",
      "accessAsUserPermissionId": "<uuid>",
      "authorityHost": "https://login.microsoftonline.com",
      "authority": "https://login.microsoftonline.com/<tenant-id>"
    }
  }
}

| Section | Required | Description | | ---------------------------------- | -------- | ---------------------------------------------------------------- | | app.shortName | Yes | Short display name in Teams (2–30 characters) | | app.fullName | Yes | Full display name in Teams (2–30 characters) | | app.projectId | Yes | Auto-generated UUID identifying the project | | endpoints.appIntegrationsBackend | Yes | URL of your App Integrations backend | | endpoints.userRegistration | No | Optional user registration URL | | teams | No | Populated after deployment with the Teams app and tenant IDs | | aad | No | Populated after deployment with the Entra (Azure AD) app details |

Typical Workflow

1. c8teams create my-app — scaffold the project and fill in your configuration.
2. cd my-app && npm install — install dependencies (including this CLI).
3. npm run build — build the deployable package into build/.
4. npm run deploy (or c8teams deploy --auth) — authenticate and provision the app to your M365 tenant.
5. c8teams show-config — copy the output YAML into your App Integrations backend configuration and set the AAD_APP_CLIENT_SECRET environment variable.
6. After an admin approves the app in the Teams Admin Center, it becomes available to your organization.

License

Apache 2.0