Getting started / Add-Ons /
Tapitalee CLI

Tapitalee CLI

Overview

The Tapitalee CLI add-on provisions an agent account for your app and injects a TAPIT_TOKEN secret environment variable into the app’s containers. Any container or task running in the app can then use the Tapitalee CLI (tapit) with read-only access to all apps in the team.

This is the equivalent of manually creating an agent account, generating an API token for it, and setting up the TAPIT_TOKEN secret yourself — all done automatically by adding this add-on.

How It Works 

Add-on → Agent account (read-only) → API token → TAPIT_TOKEN secret → App containers
  1. Agent Account: The add-on creates an agent membership named Tapitalee CLI (<app name>) in your team with read-only access.
  2. API Token: An internal API token is generated for that agent account.
  3. Secret Variable: The token is stored in a secret environment variable named TAPIT_TOKEN on the app.
  4. App Redeploy: The app is redeployed so the secret is available to its containers and tasks.
  5. CLI Access: Any process in the app that runs tapit automatically authenticates as the agent account and can read all apps in the team.

Purpose and Benefits

  • Automation-Ready: Containers and tasks can run tapit commands without any manual credential setup.
  • Ideal for AI Agents: AI agents and automation running inside your app can inspect the team’s apps and resources safely.
  • Read-Only by Design: The agent account has no write access, so automated processes cannot modify or delete resources.
  • Team-Wide Visibility: Read access spans every app in the team, not just the app the add-on is attached to.
  • Zero Manual Setup: Replaces the manual steps of creating an agent account, issuing a token, and wiring up the secret.

Prerequisites

None beyond an existing app. The add-on manages the agent account, token, and secret for you.

CLI Usage

Create Tapitalee CLI

Give this app a TAPIT_TOKEN secret for using the Tapitalee CLI, plus an agent account with read-only access to all apps in the team

tapit create tapitalee_cli [description='My Tapitalee CLI access'] [--ignore-existing]

Parameters

  • description: Description of the Tapitalee CLI add-on’s purpose
  • --ignore-existing: Skip creation if a Tapitalee CLI add-on already exists (useful for idempotent scripts)

Web UI

You can also set up the add-on through the Tapitalee web interface:

  1. Navigate to your app.
  2. Go to the Add-ons section.
  3. Click “Add Add-on” and select “Tapitalee CLI”.
  4. Optionally enter a description.
  5. Click Create.

Once provisioning completes, the app is redeployed and the TAPIT_TOKEN secret becomes available to its containers.

Only one Tapitalee CLI add-on can exist per app.

Using the CLI Inside Your App

After the add-on is active, the TAPIT_TOKEN environment variable is present in your app’s containers as a secret. Install the CLI via the instructions or use the utilitycontainer image provided for running tasks, which has tapit preinstalled.

Security Considerations

  • Read-Only Access: The agent account cannot create, modify, or delete resources — it can only read.
  • Secret Storage: The token is stored as a secret environment variable and is not shown in plaintext after creation.
  • Team Scope: The token grants read access to all apps in the team. Only add this to apps where team-wide read visibility is appropriate.
  • Automatic Rotation on Reprovision: Reprovisioning the add-on regenerates the token; the previous token value cannot be recovered after its initial creation.

Deleting the Add-On

Removing the add-on cleans up the agent account, its token, and the TAPIT_TOKEN secret. Redeploy the app afterwards if you want the variable removed from running containers.