Stripe Projects CLI Reference

Overview

Stripe Projects wraps the Stripe Projects CLI plugin so that Hermes can provision SaaS services (Neon, Twilio, Vercel, and others), generate and sync credentials into the user's .env file, and manage billing across providers from one place.

Prerequisites

• Stripe CLI installed. On macOS, use Homebrew:

  brew install stripe/stripe-cli/stripe
  

  On Linux, use your package manager or download from https://docs.stripe.com/stripe-cli/install.
• Stripe Projects plugin installed:

  stripe plugin install projects
  

• A Stripe account. If the user does not have one, the CLI can guide through sign-in or account creation in the browser during setup.

When to Use

Use Stripe Projects when the user says:

• "set up <provider>", "provision <Neon|Twilio|Vercel|...>", "create a database"
• "give me a <Postgres|Redis|Twilio number|...> for this project"
• "manage my stack credentials", "rotate this key", "upgrade my plan"
• "what providers can I add?"

If the user already has a provider account, they can connect it with stripe projects link <provider>. If the user wants to use an existing provider resource (e.g., an existing database or Vercel project), check provider support first; many providers support provisioning new resources but not importing existing ones.

Capabilities

• Initialize a project with an encrypted credential store (.projects/vault/vault.json)
• Discover available providers via catalog
• Provision a service from a provider (e.g., neon/postgres, twilio/sms, runloop/sandbox)
• Generate credentials and sync them into the user's .env file
• Record the resource in the vault
• List all added providers and their .env keys
• Upgrade a provider's tier
• Remove (deprovision) a provider
• Rotate credentials for a provider
• Link an existing provider account (if the user already has one)
• Manage billing across providers from one place

Procedures

Initialize the Project

1. Change to the project root:

   cd <project-root>
   

2. Run the init command:

   stripe projects init
   

   This creates .projects/vault/vault.json (an encrypted credential store) and prepares the project to receive providers.

Discover Available Providers

Run the catalog command:

stripe projects catalog

This lists every provider Stripe Projects supports, including databases, hosting, auth, AI, analytics, messaging, and others.

Add a Service

Use the add command with the provider and service:

stripe projects add <provider>/<service>

Examples:

• stripe projects add neon/postgres
• stripe projects add twilio/sms
• stripe projects add runloop/sandbox

The CLI provisions the service in the user's own account with the provider, generates credentials, syncs them into .env, and records the resource in the vault. The user may need to confirm a tier selection or pricing prompt.

Verify

Run the list command:

stripe projects list

This should show the newly added provider and its .env keys.

Manage, Upgrade, Remove, Rotate

Use the following commands:

stripe projects upgrade <provider>     # tier change
stripe projects remove <provider>      # deprovision
stripe projects rotate <provider>      # rotate credentials

Parameters

Parameter	Meaning	Required
provider	The provider name (e.g., neon, twilio, runloop)	Yes
service	The service name within the provider (e.g., postgres, sms, sandbox)	Yes

Constraints and Caveats

• Platform gating: The tool is gated [linux, macos] while the broader payments cluster matures on Windows. The Stripe CLI itself is cross-platform; this gate is a posture for the cluster, not a hard limit.
• .env writes are real writes: The CLI appends to whatever .env is in the project root. If the user's .env is gitignored (normal), the keys land safely; if not, this skill could be a credential-leak vector. Always check .gitignore first.
• Per-project vault: .projects/vault/vault.json is per-project. Provisioning the same service in two different projects creates two separate resources — and two bills.
• Billing: Billing happens on Stripe's side. Tier prompts during add or upgrade are real charges; surface them to the user before confirming.
• Provider availability changes: The catalog grows; if a provider the user names is not listed, use stripe projects catalog | grep <provider> first instead of failing the add call.
• Credentials security: Credentials in the vault are encrypted, but .env is plaintext. Standard .env hygiene applies — never commit it.
• Removing a service: Removing a service does NOT always destroy the underlying resource. Some providers leave a paused/dormant resource behind. Check the provider's own dashboard after remove for high-cost services (managed databases especially).

Failure Modes

• stripe projects add fails if the provider is not in the catalog. Use stripe projects catalog | grep <provider> first.
• stripe projects remove may not destroy the underlying resource. Check the provider dashboard.
• If .env is not gitignored, credential leak is possible.
• Tier prompts during add or upgrade are real charges; the user may be surprised if not surfaced before confirming.

Examples

• stripe projects add neon/postgres
• stripe projects add twilio/sms
• stripe projects add runloop/sandbox
• stripe projects upgrade <provider>
• stripe projects remove <provider>
• stripe projects rotate <provider>
• stripe projects link <provider> (for existing provider account)

Version Check

To verify the installation and list current providers:

stripe projects --version && stripe projects list

Terminal

All commands in this reference are executed in a terminal environment. Ensure you have a terminal open at the project root before running any Stripe Projects commands.