From 27494be3c4721bc9542a6b87733d5f0b37157cc1 Mon Sep 17 00:00:00 2001 From: Peter Kota Date: Wed, 28 Oct 2026 11:12:24 +0100 Subject: [PATCH] docs: bring the README in line with the Sevalla brand guidelines --- README.md | 393 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 204 insertions(+), 189 deletions(-) diff --git a/README.md b/README.md index 86081bc..8ee935f 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,25 @@
+ + # Sevalla CLI -**Manage your Sevalla infrastructure from the terminal.** +**Deploy and manage Sevalla from your terminal.** [![CI](https://github.com/sevalla/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/sevalla/cli/actions/workflows/ci.yml) -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -[![Node.js](https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white)](https://nodejs.org/) -[![npm](https://img.shields.io/npm/v/@sevalla/cli)](https://www.npmjs.com/package/@sevalla/cli) +[![npm](https://img.shields.io/npm/v/@sevalla/cli?color=57534e)](https://www.npmjs.com/package/@sevalla/cli) +[![License: MIT](https://img.shields.io/badge/license-MIT-57534e)](LICENSE) +[![Node.js](https://img.shields.io/badge/Node.js-22+-57534e?logo=node.js&logoColor=white)](https://nodejs.org/) -
+[Docs](https://docs.sevalla.com) ยท [Sevalla](https://sevalla.com) ---- + -The official CLI for the [Sevalla](https://sevalla.com) cloud platform. Deploy applications, manage databases, configure domains, monitor metrics, and more โ€” all from your terminal. Every command supports `--json` output for CI/CD scripting. +Deploy and manage applications, databases and static sites on [Sevalla](https://sevalla.com) from your terminal: trigger deployments, set environment variables, add domains, read logs and watch metrics. Every command takes `--json`, so the same commands work in scripts and CI/CD. -## Installation +## Install -```bash +```sh # Homebrew brew install sevalla/tap/sevalla @@ -28,73 +30,41 @@ npm install -g @sevalla/cli bash <(curl -fsSL https://raw.githubusercontent.com/sevalla/cli/main/install.sh) ``` -Windows binaries are available on the [releases page](https://github.com/sevalla/cli/releases/latest). - -## Quick Start - -```bash -sevalla login -sevalla apps list -``` - -## Authentication - -### Device Authorization (Interactive) +Windows binaries are on the [releases page](https://github.com/sevalla/cli/releases/latest). -The recommended way to authenticate โ€” opens your browser, no need to copy-paste tokens. +## Quick start -```bash -# Log in (opens browser for authorization) +```sh +# Sign in through your browser sevalla login -# Check auth status -sevalla auth status - -# Log out -sevalla logout -``` - -Credentials are stored at `~/.config/sevalla/credentials.json` with `0600` permissions. - -### API Token (CI/CD & Scripting) - -For non-interactive environments, set the `SEVALLA_API_TOKEN` environment variable. When set, it takes priority over stored credentials. - -```bash -# Export for the current session -export SEVALLA_API_TOKEN="your-api-token" +# List your applications and their IDs sevalla apps list -# Or inline for a single command -SEVALLA_API_TOKEN="your-api-token" sevalla apps list -``` - -You can generate an API token from **Settings > API Keys** in the [Sevalla dashboard](https://sevalla.com), or via the CLI: - -```bash -sevalla api-keys create --name "CI Token" +# Deploy an application's main branch +sevalla apps deployments trigger --branch main ``` ## Usage ### Applications -```bash +```sh sevalla apps list sevalla apps get -sevalla apps create --name myapp --source privateGit --cluster -sevalla apps update --display-name "My App" +sevalla apps create --name storefront --source privateGit --cluster +sevalla apps update --display-name "Storefront" sevalla apps delete sevalla apps activate sevalla apps suspend --confirm -sevalla apps clone --display-name "Clone" --cluster +sevalla apps clone --display-name "Storefront staging" --cluster sevalla apps purge-cache sevalla apps cdn-toggle ``` ### Deployments -```bash +```sh sevalla apps deployments list --app-id sevalla apps deployments get --app-id sevalla apps deployments trigger --branch main @@ -107,20 +77,20 @@ sevalla apps deployments logs --app-id ### Processes -```bash +```sh sevalla apps processes list --app-id sevalla apps processes get --app-id sevalla apps processes create --name web --type web --resource-type sevalla apps processes update --app-id --instances 3 -sevalla apps processes delete --app-id +sevalla apps processes delete --app-id --confirm sevalla apps processes trigger --app-id sevalla apps processes disk update --app-id --resource-type --mount-path /var/lib/data sevalla apps processes disk delete --app-id --confirm ``` -### Process Metrics +### Process metrics -```bash +```sh sevalla apps processes metrics cpu-usage sevalla apps processes metrics cpu-limit sevalla apps processes metrics memory-usage @@ -128,38 +98,39 @@ sevalla apps processes metrics memory-limit sevalla apps processes metrics instance-count ``` -### Application Domains +### Application domains -```bash +```sh sevalla apps domains list --app-id -sevalla apps domains add --name example.com +sevalla apps domains add --name shop.example.com sevalla apps domains get --app-id -sevalla apps domains update --app-id --name my-app +sevalla apps domains update --app-id --name storefront sevalla apps domains delete sevalla apps domains set-primary sevalla apps domains toggle sevalla apps domains refresh-status ``` -### Application Environment Variables +### Application environment variables -```bash -sevalla apps env-vars list --app-id # values hidden; add --show-values +```sh +# Values are hidden; add --show-values to see them +sevalla apps env-vars list --app-id sevalla apps env-vars create --key MY_VAR --value "my value" sevalla apps env-vars update --app-id --value "new value" sevalla apps env-vars delete ``` -### Application Logs +### Application logs -```bash +```sh sevalla apps logs runtime sevalla apps logs access ``` -### Application Metrics +### Application metrics -```bash +```sh sevalla apps metrics requests-per-minute sevalla apps metrics response-time sevalla apps metrics response-time-avg @@ -170,32 +141,32 @@ sevalla apps metrics slowest-requests sevalla apps metrics top-pages ``` -### Application IP Restriction +### Application IP restriction -```bash +```sh sevalla apps ip-restriction get sevalla apps ip-restriction update --type allow --ip-list "1.2.3.4,5.6.7.8" --enabled true ``` -### TCP Proxies +### TCP proxies -```bash +```sh sevalla apps tcp-proxies list --app-id sevalla apps tcp-proxies create --process-id --port 3000 sevalla apps tcp-proxies delete ``` -### Private Ports +### Private ports -```bash +```sh sevalla apps private-ports list --app-id sevalla apps private-ports create --process-id --port 8080 sevalla apps private-ports delete ``` -### Deployment Hook +### Deployment hook -```bash +```sh sevalla apps deployment-hook get sevalla apps deployment-hook enable sevalla apps deployment-hook disable --confirm @@ -204,39 +175,39 @@ sevalla apps deployment-hook regenerate --confirm ### Databases -```bash +```sh sevalla databases list sevalla databases get -sevalla databases create --name mydb --type postgresql --db-version 16 \ - --cluster --resource-type --db-name mydb --db-password secret -sevalla databases update --display-name "My DB" +sevalla databases create --name storefront-db --type postgresql --db-version 16 \ + --cluster --resource-type --db-name storefront --db-password "$DB_PASSWORD" +sevalla databases update --display-name "Storefront DB" sevalla databases delete sevalla databases activate sevalla databases suspend --confirm -sevalla databases reset-password --new-password --confirm +sevalla databases reset-password --new-password "$DB_PASSWORD" --confirm ``` -### Database Backups +### Database backups -```bash +```sh sevalla databases backups list --db-id sevalla databases backups create --name nightly sevalla databases backups delete sevalla databases backups restore --confirm ``` -### Database Connections +### Database connections -```bash +```sh sevalla databases connections internal-list --db-id sevalla databases connections internal-create --target-id sevalla databases connections internal-delete sevalla databases connections external-toggle ``` -### Database Metrics +### Database metrics -```bash +```sh sevalla databases metrics cpu-usage sevalla databases metrics cpu-limit sevalla databases metrics memory-usage @@ -247,27 +218,27 @@ sevalla databases metrics all-storage sevalla databases metrics used-storage ``` -### Database IP Restriction +### Database IP restriction -```bash +```sh sevalla databases ip-restriction get sevalla databases ip-restriction update --type allow --ip-list "1.2.3.4" --enabled true ``` -### Static Sites +### Static sites -```bash +```sh sevalla static-sites list sevalla static-sites get -sevalla static-sites create --name mysite --repository user/repo --branch main -sevalla static-sites update --display-name "My Site" +sevalla static-sites create --name storefront-docs --repository user/repo --branch main +sevalla static-sites update --display-name "Storefront docs" sevalla static-sites delete sevalla static-sites purge-cache ``` -### Static Site Deployments +### Static site deployments -```bash +```sh sevalla static-sites deployments list --site-id sevalla static-sites deployments get --site-id sevalla static-sites deployments trigger --branch main @@ -275,37 +246,37 @@ sevalla static-sites deployments cancel --site-id sevalla static-sites deployments logs --site-id ``` -### Static Site Domains +### Static site domains -```bash +```sh sevalla static-sites domains list --site-id sevalla static-sites domains get --site-id -sevalla static-sites domains add --name example.com -sevalla static-sites domains update --site-id --name my-site +sevalla static-sites domains add --name docs.example.com +sevalla static-sites domains update --site-id --name storefront-docs sevalla static-sites domains delete sevalla static-sites domains set-primary sevalla static-sites domains toggle sevalla static-sites domains refresh-status ``` -### Static Site Environment Variables +### Static site environment variables -```bash +```sh sevalla static-sites env-vars list --site-id sevalla static-sites env-vars create --key MY_VAR --value "my value" sevalla static-sites env-vars update --site-id sevalla static-sites env-vars delete ``` -### Static Site Logs +### Static site logs -```bash +```sh sevalla static-sites logs access ``` -### Static Site Metrics +### Static site metrics -```bash +```sh sevalla static-sites metrics requests-per-minute sevalla static-sites metrics response-time sevalla static-sites metrics response-time-avg @@ -316,94 +287,95 @@ sevalla static-sites metrics slowest-requests sevalla static-sites metrics top-pages ``` -### Load Balancers +### Load balancers -```bash +```sh sevalla load-balancers list sevalla load-balancers get -sevalla load-balancers create --name mylb -sevalla load-balancers update --display-name "My LB" +sevalla load-balancers create --name storefront-lb +sevalla load-balancers update --display-name "Storefront LB" sevalla load-balancers delete ``` -### Load Balancer Destinations +### Load balancer destinations -```bash +```sh sevalla load-balancers destinations list --lb-id sevalla load-balancers destinations create --service-type APP --service-id sevalla load-balancers destinations toggle sevalla load-balancers destinations delete ``` -### Load Balancer Domains +### Load balancer domains -```bash +```sh sevalla load-balancers domains list --lb-id sevalla load-balancers domains get --lb-id -sevalla load-balancers domains add --name example.com -sevalla load-balancers domains update --lb-id --name my-lb +sevalla load-balancers domains add --name shop.example.com +sevalla load-balancers domains update --lb-id --name storefront-lb sevalla load-balancers domains delete sevalla load-balancers domains set-primary sevalla load-balancers domains toggle sevalla load-balancers domains refresh-status ``` -### Object Storage +### Object storage -```bash +```sh sevalla object-storage list sevalla object-storage get -sevalla object-storage create --name mybucket -sevalla object-storage update --display-name "My Bucket" +sevalla object-storage create --name storefront-assets +sevalla object-storage update --display-name "Storefront assets" sevalla object-storage delete +sevalla object-storage rotate-credentials --old-keys-ttl-hours 24 --confirm ``` -### Object Storage CDN Domain +### Object storage CDN domain -```bash +```sh sevalla object-storage cdn-domain enable sevalla object-storage cdn-domain disable ``` -### Object Storage CORS Policies +### Object storage CORS policies -```bash +```sh sevalla object-storage cors-policies list --bucket-id sevalla object-storage cors-policies create --origins "*" --methods GET,HEAD sevalla object-storage cors-policies update --bucket-id --origins "*" --methods GET sevalla object-storage cors-policies delete ``` -### Object Storage Objects +### Object storage objects -```bash +```sh sevalla object-storage objects list --bucket-id sevalla object-storage objects delete --keys a.txt,b.txt --confirm ``` ### Pipelines -```bash +```sh sevalla pipelines list sevalla pipelines get -sevalla pipelines create --name mypipeline --type trunk -sevalla pipelines update --name "My Pipeline" +sevalla pipelines create --name storefront --type trunk +sevalla pipelines update --name "Storefront" sevalla pipelines delete sevalla pipelines promote --source-app-id --target-app-ids , ``` -### Pipeline Stages +### Pipeline stages -```bash +```sh sevalla pipelines stages create --name staging sevalla pipelines stages delete sevalla pipelines stages apps add -sevalla pipelines stages apps remove +sevalla pipelines stages apps remove --confirm ``` -### Pipeline Preview +### Pipeline preview -```bash +```sh sevalla pipelines preview enable sevalla pipelines preview disable sevalla pipelines preview update --auto-create-app true @@ -414,32 +386,32 @@ sevalla pipelines preview create-app --branch feature/checkout --p ### Projects -```bash +```sh sevalla projects list sevalla projects get -sevalla projects create --name myproject -sevalla projects update --name "My Project" +sevalla projects create --name storefront +sevalla projects update --name "Storefront" sevalla projects delete sevalla projects services add --service-id -sevalla projects services remove +sevalla projects services remove --confirm ``` -### Docker Registries +### Docker registries -```bash +```sh sevalla docker-registries list sevalla docker-registries get -sevalla docker-registries create --name myregistry --username user --secret token +sevalla docker-registries create --name storefront-registry --username --secret "$REGISTRY_TOKEN" sevalla docker-registries update sevalla docker-registries delete ``` ### Webhooks -```bash +```sh sevalla webhooks list sevalla webhooks get -sevalla webhooks create --endpoint https://example.com/hook --events "deployment.started" +sevalla webhooks create --endpoint https://shop.example.com/webhooks/sevalla --events "deployment.started" sevalla webhooks update sevalla webhooks delete sevalla webhooks toggle @@ -448,12 +420,12 @@ sevalla webhooks deliveries list --webhook-id sevalla webhooks deliveries get --webhook-id ``` -### API Keys +### API keys -```bash +```sh sevalla api-keys list sevalla api-keys get -sevalla api-keys create --name "My Key" +sevalla api-keys create --name "Storefront deploys" sevalla api-keys update sevalla api-keys delete sevalla api-keys toggle @@ -461,9 +433,9 @@ sevalla api-keys rotate --confirm sevalla api-keys validate ``` -### Global Environment Variables +### Global environment variables -```bash +```sh sevalla global-env-vars list sevalla global-env-vars create --key MY_VAR --value "my value" sevalla global-env-vars update @@ -472,7 +444,7 @@ sevalla global-env-vars delete ### Resources -```bash +```sh sevalla resources clusters sevalla resources db-types sevalla resources disk-types @@ -481,86 +453,129 @@ sevalla resources process-types ### Git -```bash +```sh sevalla git providers ``` ### Users -```bash +```sh sevalla users list ``` -## Global Options +### Global options Every command accepts these flags: -| Option | Description | -|--------|-------------| -| `--json` | Output as JSON (for scripting and CI/CD) | -| `--api-url ` | Override API base URL | -| `--confirm` | Required by commands that delete data or can't be undone (suspend, restore, reset or rotate credentials) | -| `--version` | Show version | -| `--help` | Show help | +| Option | Description | +| ----------------- | -------------------------------------------------------------------------------------------------------- | +| `--json` | Output as JSON, for scripts and CI/CD | +| `--api-url ` | Override the API base URL | +| `--confirm` | Required by commands that delete data or can't be undone (suspend, restore, reset or rotate credentials) | +| `--version` | Show the version | +| `--help` | Show help | -```bash +```sh # Pipe JSON output to jq sevalla apps list --json | jq '.[].name' -# Use in scripts +# Use it in scripts APP_ID=$(sevalla apps list --json | jq -r '.[0].id') -sevalla apps get $APP_ID --json +sevalla apps get "$APP_ID" --json ``` -## Shell Completion +### Shell completion -Enable tab completion for commands, subcommands, and options. +Tab completion for commands, subcommands and options. -### Bash - -```bash -# Add to ~/.bashrc +```sh +# Bash: add to ~/.bashrc eval "$(sevalla completion bash)" ``` -### Zsh - -```bash -# Add to ~/.zshrc +```sh +# Zsh: add to ~/.zshrc eval "$(sevalla completion zsh)" ``` -### Fish - -```bash -# Add to ~/.config/fish/config.fish +```sh +# Fish: add to ~/.config/fish/config.fish sevalla completion fish | source ``` -## Environment Variables +## Authentication + +### Device authorization (interactive) + +The recommended way to sign in: it opens your browser, so there's no token to copy and paste. + +```sh +# Sign in through your browser +sevalla login + +# Check that you're signed in +sevalla auth status + +# Sign out +sevalla logout +``` + +Credentials are stored at `~/.config/sevalla/credentials.json` with `0600` permissions. + +### API token (CI/CD and scripting) + +For non-interactive environments, set `SEVALLA_API_TOKEN`. When it's set, it takes priority over stored credentials. In CI, set it from your secret store rather than pasting it into a script. -| Variable | Description | -|----------|-------------| +```sh +# For the current session +export SEVALLA_API_TOKEN= +sevalla apps list + +# For a single command +SEVALLA_API_TOKEN= sevalla apps list +``` + +Create a token under **Settings โ†’ API keys** in the [Sevalla dashboard](https://app.sevalla.com), or with the CLI: + +```sh +sevalla api-keys create --name "CI token" +``` + +### Environment variables + +| Variable | Description | +| ------------------- | ----------------------------------------------------------- | | `SEVALLA_API_TOKEN` | API token for authentication (overrides stored credentials) | -| `SEVALLA_API_URL` | Override API base URL | +| `SEVALLA_API_URL` | Override the API base URL | ## Development -```bash +```sh git clone https://github.com/sevalla/cli.git -cd sevalla-cli +cd cli npm install ``` -```bash -npm run dev -- apps list # Run in development -npm test # Run tests (node:test) -npm run typecheck # Type check (tsc --noEmit) -npm run lint # Lint (eslint) -npm run format:check # Format check (prettier) -npm run build # Build (tsup) +```sh +# Run in development +npm run dev -- apps list + +# Run tests (node:test) +npm test + +# Type check (tsc --noEmit) +npm run typecheck + +# Lint (eslint) +npm run lint + +# Check formatting (prettier) +npm run format:check + +# Build (tsup) +npm run build ``` ## License -[MIT](LICENSE) +MIT. See [LICENSE](LICENSE).