Ramp CLI

Public command-line client for Ramp.

This repository contains the CLI only. It talks to the hosted Ramp API, while the main Ramp application/backend remains private and is not included here.

Open Source Boundary

• This repo is the public CLI source code.
• The Ramp web app, API internals, and deployment platform are not part of this repository.
• End users can install and use the CLI normally against Ramp.
• Some local development flows in this repo expect access to a Ramp backend instance.

Install

Requires Node 24+.

pnpm add -g @ramp-sh/cli

Or run it without installing:

pnpm dlx @ramp-sh/cli --help

Login

ramp login

You can also provide email up front:

ramp login --email [email protected]

Or use an existing API token (useful for CI):

ramp login --token rmp_cli_... --api-url https://api.ramp.sh

Check current identity:

ramp whoami

Link current project (creates .ramp/config.json):

ramp link

Add .ramp/ to your app repo .gitignore so local project links do not get committed.

Unlink current project:

ramp unlink

Show app status (auto-resolves project):

ramp status

List account apps and servers:

ramp apps
ramp servers

Fetch logs and execute commands:

ramp logs --type laravel
ramp exec "php artisan about"
ramp run migrate
ramp run --list

Manage env vars:

ramp env list
ramp env set APP_ENV production
ramp env delete APP_ENV
ramp env pull --output .env
ramp env push --file .env

Create app and auto-link current directory:

ramp create

Initialize a new ramp.yaml:

ramp init
ramp init --template laravel
ramp init --template rails
ramp init --template ruby
ramp init --template bun
ramp init --template elysia
ramp init --template rust
ramp init --template axum
ramp init --template reverb
ramp init --template laravel-octane
ramp init --template adonis
ramp init --template nextjs
ramp init --template static
ramp init --template worker
ramp init --template node-api --yes --print
ramp init --template laravel --yes --json

Trigger deploy (auto-resolves project):

ramp deploy

Rollback app (latest successful deploy by default):

ramp rollback

Logout:

ramp logout

Usage

pnpm dlx @ramp-sh/cli validate

validate uses remote API validation only. Default API URL is https://api.ramp.sh (or RAMP_API_URL if set). Remote validation requires a CLI token from ramp login. Use --server <id-or-name> to include server-level collision checks (ports/domains).

CI/CD auth can use RAMP_TOKEN directly (takes precedence over local credentials file).

Auto project resolution (used by status and deploy) priority:

1. --app / --server flags
2. .ramp/config.json link file
3. nearest ramp.yaml stack lookup via API

Remote validation against local app:

pnpm dlx @ramp-sh/cli validate --api-url http://localhost:8000

Validate a specific file:

pnpm dlx @ramp-sh/cli validate ./path/to/ramp.yaml

JSON output:

pnpm dlx @ramp-sh/cli validate --json

Strict mode (warnings fail with exit code 2):

pnpm dlx @ramp-sh/cli validate --strict

Init templates

ramp init supports:

• custom
• laravel
• rails
• ruby
• bun
• elysia
• rust
• axum
• reverb
• laravel-octane
• node-api
• nextjs
• adonis
• static
• worker

When ramp.yaml already exists, interactive mode offers overwrite, merge, or cancel. With --yes, existing files default to a safe merge; use --force to overwrite. Use --json to emit metadata for scripting. The JSON payload includes the generated YAML.

Local development

Use Node 24+ for local development in this repository.

pnpm install
pnpm build
pnpm test
node dist/bin.js validate fixtures/valid.ramp.yaml

For local development against a Ramp backend, point the CLI at a reachable API instance with --api-url or RAMP_API_URL.

If you need to refresh the bundled schema from another checkout, provide the source explicitly:

RAMP_SCHEMA_SOURCE=../app/docs/ramp/ramp.schema.json pnpm sync-schema

Quality Checks

pnpm format
pnpm lint
pnpm check
pnpm verify

pnpm install also configures repo-local git hooks via .githooks/:

• pre-commit runs Biome formatting checks on staged files
• pre-push runs pnpm typecheck and pnpm test

The repository uses Biome as a formatter baseline in CI today. The lint command is available for deeper cleanup as the codebase evolves.