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://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 sync --from .env.local --service web
ramp env upload --from .env
ramp env push --file .env

ramp env sync is an upsert. It reports created keys, readable value changes, sealed values written, and unchanged keys. For sealed values, the CLI sends a local-only HMAC fingerprint so repeated syncs from the same machine can be reported as unchanged without making the secret readable to Ramp. Readable changes include a small - old / + new diff. Use --json to see created, changed, sealed-written, unchanged, skipped key lists, and readable diffs.

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://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.

ramp init also detects dotenv files in the current directory (.env.example, .env, .env.local) and adds env keys as input_yours placeholders on the selected service. Secret values are never copied into ramp.yaml. Use --env-file <path> to detect keys from a specific file, or --no-detect-env to skip detection.

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.