CLI Reference

Installation

brew tap bitfootco/tap
brew install kyper

Or download the latest binary for your platform from github.com/bitfootco/kyper-cli/releases.

Global flags

Available on all commands (unless noted).

Authentication

kyper login

Opens your browser to complete a device authorization flow, then saves the API token to ~/.kyper/config.yml (0600 permissions).

$ kyper login
Opening browser to https://kyper.shop/device?code=A3F2B1C4
Waiting for authorization... done!
Logged in as [email protected]

kyper whoami

Display the email and role of the currently authenticated user.

$ kyper whoami
[email protected] (developer)

Project Setup

kyper init

Interactive project setup wizard — auto-detects your stack, walks through a 9-step configuration flow, and writes kyper.yml + .kyperignore. Requires an interactive terminal; does not support --json.

kyper init

Auto-detects: Rails, Django, Laravel, Go, Next.js, NestJS, Express, Koa — plus any Dockerized app.

kyper check

Validates kyper.yml and confirms the Dockerfile exists — no network or Docker required. Add --quick to skip the Dockerfile check.

$ kyper check
✓ kyper.yml is valid
✓ Dockerfile exists

All checks passed

  Warnings:
  - App uses postgres but has no on_deploy hook (migrations may be missing)

kyper validate deprecated

Alias for kyper check. Will be removed in a future release.

Deploy

kyper build

Build your Docker image locally using the same pipeline as the remote build. Add --scan to run the same Trivy security gate. Requires Docker (and Trivy for --scan) installed locally.

$ kyper build --scan
✓ kyper.yml is valid
Building kyper-local/my-rails-app:1.0.0...
...
✓ Build succeeded
Scan result: PASSED — 0 critical fixable

The image is tagged kyper-local/<name>:<version> and never pushed to any registry.

kyper tag

Bump the version in kyper.yml. Omit --bump for an interactive picker. Patch and minor updates auto-deploy to subscribers; major bumps require consumer opt-in.

kyper tag --bump patch  # 1.0.0 → 1.0.1
kyper tag --bump minor  # 1.0.0 → 1.1.0
kyper tag --bump major  # 1.0.0 → 2.0.0

kyper push

Validates, archives, uploads, and tails the remote build log in real-time. Re-pushing the same version number while it is pending, building, or in review automatically replaces the prior submission.

$ kyper push
✓ kyper.yml is valid
✓ Archived 42 files (1.2 MB)
✓ App synced: my-rails-app
✓ Version 1.0.0 uploaded — build started
[build] ...
✓ Build complete — submitted for review

Subcommands

kyper test

Build and ephemerally deploy your app on Kyper's real K8s infrastructure with a live HTTPS URL. Declared deps (Postgres, Redis, etc.) are provisioned. Auto-destroys after 1 hour. Limit: 1 active test deploy, 3 builds per day.

$ kyper test
✓ kyper.yml is valid
✓ Test deploy queued
[build] ...
✓ Build succeeded
[provision] Starting postgres dep...
✓ Test deploy is live!
  https://test-my-rails-app-a1b2c3.apps.kyper.shop
  Auto-destroys in 59 minutes.

Utility

kyper version

Print CLI version, commit hash, and build date.

$ kyper version
kyper v0.4.0 (a1b2c3d, 2026-02-15)

Configuration

The CLI stores its token in ~/.kyper/config.yml (0600 permissions). Override the host via KYPER_HOST env var or --host flag.

# ~/.kyper/config.yml
token: kpr_a1b2c3d4e5f6...
host: https://kyper.shop

CI / Automation

Bootstrap authentication by writing the config file directly. Store your token as a CI secret.

mkdir -p ~/.kyper
echo "token: $KYPER_TOKEN" > ~/.kyper/config.yml
chmod 600 ~/.kyper/config.yml

Example: GitHub Actions

# .github/workflows/deploy.yml
name: Deploy to Kyper
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Kyper CLI
        run: |
          curl -sL https://github.com/bitfootco/kyper-cli/releases/latest/download/kyper_linux_amd64.tar.gz | tar xz
          sudo mv kyper /usr/local/bin/
      - name: Configure Kyper
        run: |
          mkdir -p ~/.kyper
          echo "token: ${{ secrets.KYPER_TOKEN }}" > ~/.kyper/config.yml
          chmod 600 ~/.kyper/config.yml
      - run: kyper tag --bump patch --json
      - run: kyper push --json

Scripting with --json

kyper push status --json | jq -r '.latest_version.status'
kyper check --json | jq '.errors[]'

Quick reference