CLI

The DevRamps CLI (@devramps/cli) manages authentication, AI agent setup, and AWS infrastructure bootstrapping.

Installation

Run directly with npx (no installation required):

npx @devramps/cli <command>

Or install globally:

npm install -g @devramps/cli
devramps <command>

Commands

Command	Description
login	Authenticate with DevRamps and store credentials
init-agent	Set up AI agent integration for a project
bootstrap	Provision AWS IAM roles and resources for your pipeline

The Login Command

Authenticates with DevRamps via browser OAuth and stores credentials in ~/.devramps/configuration.json for future use. Both the CLI and the MCP server tools read credentials from this file.

npx @devramps/cli login

Run this before using bootstrap or any MCP tools that require authentication. Credentials persist across sessions until they expire, so you only need to log in once.

Options

Option	Description
--endpoint-override <url>	Override the DevRamps API endpoint (for testing)

The Init-Agent Command

Sets up AI agent integration for the current project. Creates the configuration files that allow AI coding agents (Claude Code, Cursor, Codex, etc.) to use DevRamps MCP tools.

npx @devramps/cli init-agent

This creates:

File	Purpose
.mcp.json	Registers the DevRamps MCP server with your AI agent
DEVRAMPS_AGENTS.md	Rules the agent follows when generating infrastructure and pipelines
CLAUDE.md	Loads the rules into Claude Code / Codex
AGENTS.md	Loads the rules into Cursor / Windsurf / other agents

The command is safe to run multiple times. It won't overwrite existing files, and will merge into an existing .mcp.json if one exists.

Options

Option	Description
-y, --yes	Skip the confirmation prompt

After running, restart your AI agent to pick up the new MCP server. See Set Up with an AI Agent for the full workflow.

Prerequisites

• Node.js 18+: Install Node.js.
• AWS CLI: Configured with credentials that can assume roles in your target accounts.

aws configure
# or
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key

The Bootstrap Command

The bootstrap command reads your pipeline definitions and creates CloudFormation stacks in each target AWS account.

npx @devramps/cli bootstrap [options]

Options

Option	Description	Default
--target-account-role-name <name>	IAM role to assume in target accounts. Use this if your accounts don't use AWS Organizations.	OrganizationAccountAccessRole (fallback: AWSControlTowerExecution)
--pipeline-slugs <slugs>	Comma-separated list of pipeline slugs to bootstrap.	All pipelines
--dry-run	Show what would be created without actually deploying.	false
--verbose	Enable verbose logging.	false

Examples

Bootstrap all pipelines:

npx @devramps/cli bootstrap

Bootstrap specific pipelines:

npx @devramps/cli bootstrap --pipeline-slugs my-api,my-frontend

Preview without deploying:

npx @devramps/cli bootstrap --dry-run

Use a custom cross-account role:

npx @devramps/cli bootstrap --target-account-role-name MyCustomRole

What Gets Created

For each pipeline and target account combination, the CLI creates a CloudFormation stack named DevRamps-<pipeline-slug>-Bootstrap containing:

OIDC Identity Provider

An OpenID Connect identity provider (devramps.com) that enables secure, credential-less authentication. DevRamps uses OIDC federation instead of long-lived access keys -- no secrets are stored anywhere.

IAM Role

An IAM role (DevRamps-CICD-DeploymentRole) with:

• Trust policy: Allows only your specific organization and pipeline to assume the role via OIDC.
• Step permissions: Least-privilege policies for each step type used in your pipeline (ECS, EKS, Terraform, etc.).
• Additional policies: Any custom policies you've defined in aws_additional_iam_policies.yaml.

Project Structure

The CLI expects your repository to have a .devramps/ folder:

your-repo/
├── .devramps/
│   ├── my-api/
│   │   ├── pipeline.yaml                        # Required
│   │   └── aws_additional_iam_policies.yaml     # Optional
│   └── my-frontend/
│       └── pipeline.yaml
└── ... your application code

Additional IAM Policies

If your pipeline needs AWS permissions beyond what the built-in step types provide (e.g., for Terraform to manage custom resources), add them in aws_additional_iam_policies.yaml:

- Version: "2012-10-17"
  Statement:
    - Effect: Allow
      Action:
        - s3:GetObject
        - s3:PutObject
        - s3:DeleteObject
      Resource: "arn:aws:s3:::my-bucket/*"
    - Effect: Allow
      Action:
        - dynamodb:*
      Resource: "arn:aws:dynamodb:*:*:table/my-table"

Or in JSON format (aws_additional_iam_policies.json):

[
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": ["s3:GetObject", "s3:PutObject"],
        "Resource": "arn:aws:s3:::my-bucket/*"
      }
    ]
  }
]

Authentication Flow

When you run bootstrap, the CLI:

1. Opens your browser to the DevRamps authentication page.
2. You log in and select your organization.
3. The CLI receives an authentication token.
4. The token is used to fetch your organization's configuration.
5. Bootstrap proceeds with the authenticated context.

The authentication flow has a 5-minute timeout. If the browser doesn't open automatically, check for popup blockers.

Troubleshooting

"Could not find .devramps folder"

Make sure you're running the CLI from your repository root, where the .devramps/ folder is located.

"No AWS credentials found"

Configure AWS credentials:

aws configure
# or set environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
# or use SSO
aws sso login

"Unable to assume role"

Your credentials don't have permission to assume the target account role. Verify:

1. The role exists in the target account.
2. Your credentials have sts:AssumeRole permission for that role.
3. The role's trust policy allows your identity.

Try a different role:

npx @devramps/cli bootstrap --target-account-role-name MyCustomRole

"Authentication timed out"

The browser authentication has a 5-minute timeout. Make sure:

1. Your browser opened the DevRamps authentication page.
2. You completed login and organization selection.
3. No popup blocker is preventing the page from opening.

CI/CD Account vs. Target Accounts

DevRamps uses two kinds of AWS accounts:

• CI/CD Account: A central account that stores shared resources — ECR repositories for Docker images, S3 buckets for bundles, Terraform state files, and KMS encryption keys. This is referenced in expressions as organization.cicd_account_id. If you use AWS Organizations, this is typically a dedicated account; otherwise, it can be the same as one of your target accounts.

• Target Accounts: The accounts where your application actually runs. Each pipeline stage specifies a target account in its account_id field. These are where ECS services, EKS clusters, EC2 instances, and other infrastructure live.

Cross-Account Roles

The default role name (OrganizationAccountAccessRole) assumes you're using AWS Organizations, where member accounts have this role created automatically. If you're not using AWS Organizations:

• Create an IAM role in each target account that your bootstrap credentials can assume.
• Use --target-account-role-name to specify the role name.
• The role needs administrator access (for creating CloudFormation stacks with IAM resources).

Permissions Required

The IAM user or role running bootstrap needs:

• sts:AssumeRole — To assume the cross-account role in each target account.
• The cross-account role itself needs administrator access (or at minimum: CloudFormation, IAM, and STS permissions) to create the bootstrap stack.

After bootstrapping, the created DevRamps-CICD-DeploymentRole has only the minimum permissions needed for your pipeline's step types.

Uninstalling / Cleanup

To remove DevRamps from an AWS account, delete the CloudFormation stack created by bootstrap:

1. Open the AWS CloudFormation console in the target account.
2. Find the stack named DevRamps-<pipeline-slug>-Bootstrap.
3. Delete the stack.

This removes the IAM role, OIDC provider, and all associated resources. Deleting the stack does not affect your running applications — it only removes DevRamps' access to the account.

When to Re-bootstrap

Re-run bootstrap when:

• You add a new step type to your pipeline (e.g., adding EKS steps to a pipeline that only had ECS).
• You update aws_additional_iam_policies.yaml with new custom permissions.
• You add a new target account to your pipeline stages.

Re-bootstrapping updates the existing CloudFormation stack — it does not create duplicate resources.