Installation
This guide covers setting up the Shift Platform for local development and installing the standalone CLI binary.
Prerequisites
Required
| Tool | Version | Install |
|---|---|---|
| Bun | >= 1.0 | curl -fsSL https://bun.sh/install | bash |
| Git | any | Pre-installed on macOS/Linux |
Optional (for production-like environments)
| Tool | Purpose | Install |
|---|---|---|
| Docker | Container builds | Docker Desktop or brew install docker |
| kind | Local Kubernetes clusters | brew install kind |
| kubectl | Kubernetes CLI | brew install kubectl |
| Doppler | Secrets management | brew install dopplerhq/cli/doppler |
Clone the Repository
The platform uses git submodules for each service. Always clone with --recurse-submodules:
git clone --recurse-submodules https://github.com/the-shift-dev/platform.git
cd platform
If you already cloned without submodules, initialize them:
git submodule update --init --recursive
Install Dependencies
bun install
This installs dependencies for the root workspace and all service packages.
If you encounter issues with @shift/platform-core not being found in submodules, try running bun install again. The Bun cache may hold a stale version of the shared package.
Start the Dev Server
bun run dev
This starts all services, the gateway on port 3000, and the platform web UI on port 4100.
Building the Shift CLI
The standalone CLI binary bundles all service CLIs into a single executable. It connects to the gateway at app.the-shift.dev by default (configurable).
Build
make build-cli
This compiles the CLI using Bun's bundler and outputs it to dist/cli/.
Install
Copy the binary to your PATH:
mkdir -p ~/.shift/bin
cp dist/cli/shift-cli ~/.shift/bin/shift-cli
Add ~/.shift/bin to your PATH in ~/.zshrc or ~/.bashrc:
export PATH="$HOME/.shift/bin:$PATH"
Reload your shell:
source ~/.zshrc
Build for All Platforms
To build binaries for macOS (arm64, x64) and Linux (x64):
make build-cli-all
Binaries are output to dist/cli/.
Verify
Check that the CLI is installed and can reach the gateway:
shift-cli status
You should see the gateway health status, including the service name and version.
Configure the Gateway URL
By default, the standalone CLI connects to https://app.the-shift.dev. To point it at your local dev server:
shift-cli config set gateway-url http://localhost:3000
To check the current setting:
shift-cli config get gateway-url
Next Steps
- Authentication -- Set up Google OAuth or API keys
- Quickstart -- Run the platform and seed sample data
- First App Tutorial -- Build something with the CLI in 10 minutes