Skip to main content

Install Starlake CLI

Starlake CLI is the command-line interface for the Starlake data pipeline platform. It runs on Linux, macOS, and Windows, and is also available as a Docker image. The CLI requires Java 17 or higher, except for Docker which includes all dependencies. Once installed, the CLI provides commands to bootstrap projects, load data, run SQL transformations, and start the Cockpit.

Install Starlake on Linux, macOS, Windows, or Docker​

Choose the method that matches your environment. Docker is the fastest option because it does not require Java.

Step-by-Step Overview​

  1. Choose an installation method -- Docker (no Java needed), Linux/macOS (Java 17+), or Windows (Java 17+ and PowerShell 5.0+).
  2. Run the installation command -- See the platform-specific tabs below.
  3. Verify the installation -- Run starlake --version. The output should display the version number.
  4. Start the Cockpit (optional) -- Run starlake serve and open http://localhost:9900.

Prerequisites for Linux and macOS​

  • Java 17+ installed 
    # Verify Java version
    java -version
  • If needed, install Java from Oracle JDK or OpenJDK

Install Starlake on Linux or macOS​

Run the one-line installation script:

bash <(curl -sL https://starlake.ai/setup.sh)

The script creates the following directory structure:

starlake/
├── bin/
│   ├── deps/      # Extra dependencies (e.g., Oracle client)
│   ├── sl         # Starlake CLI
│   └── spark      # Embedded Spark runtime

Verify Your Starlake Installation​

Run the following command to confirm the CLI is installed:

starlake --version

Expected output:

Starlake Version 1.3.4

Start the Starlake Cockpit​

Launch the Cockpit with:

starlake serve

Open http://localhost:9900 in your browser.

To use a different port, set the SL_API_HTTP_PORT environment variable:

SL_API_HTTP_PORT=11000 starlake serve

To access the Cockpit from a remote machine, set SL_API_DOMAIN to your server's domain or IP address:

SL_API_DOMAIN=your.domain.com starlake serve
Store data outside the installation folder

When creating projects through the Cockpit, projects and the management database are stored in the starlake installation folder by default. To ensure they survive reinstalls and upgrades, configure an external location using these environment variables before creating any projects:

  • SL_API_PROJECTS_ROOT — path where projects are stored
  • SL_API_JDBC_URL — JDBC URL for the user and project management database (PostgreSQL)
export SL_API_PROJECTS_ROOT=/path/to/my/projects
export SL_API_JDBC_URL=jdbc:postgresql://localhost:5432/starlake

Starlake VS Code Extension​

Starlake provides an official VS Code extension for editing project configuration files.

Install the VS Code Extension​

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search for "Starlake"
  4. Install "Starlake Data Pipeline Tools"

The extension provides:

  • Syntax highlighting for Starlake YAML configurations
  • Schema validation for application.sl.yml and domain files
  • SQL transformation snippets
  • Pipeline visualization
  • Starlake Skills for AI-assisted data pipeline development in Claude Code, GitHub Copilot, and other AI coding assistants
note

The VS Code extension requires the Starlake Cockpit to be running in the background. Start it with starlake serve before using the extension.

Upgrade Starlake to a Newer Version​

Run the upgrade command to fetch and install a newer version:

starlake upgrade

The upgrade process performs three steps:

  1. Version selection -- Retrieves the latest snapshot version and the five most recent release versions. You choose which one to install.
  2. Configuration update -- Updates SL_VERSION in your versions.sh (or versions.bat) file.
  3. Artifact download -- Deletes old JARs and downloads the new starlake-core and starlake-api files to ./bin/sl/ and ./bin/api/lib/.

Troubleshooting Starlake Installation​

Common installation issues and solutions:

  1. Java version mismatch

    # Check Java version
    java -version
    # Install Java 17+ if needed from Oracle JDK or OpenJDK

  2. Permission issues on Linux/macOS

    chmod +x bin/starlake

  3. Docker issues

    # Verify Docker installation
    docker --version

    # Test Docker permissions
    docker run hello-world
Extra Dependencies

Any additional libraries (e.g., Oracle client) should be copied to the bin/deps folder.

Next Steps​

The exhaustive list of configuration options can be found in the api-env-vars.md file.

Continue with the CLI by following the tutorials below:

Frequently Asked Questions​

What are the prerequisites to install Starlake?​

For Linux and macOS, you need Java 17 or higher installed. For Windows, you also need PowerShell 5.0 or later and administrator privileges. The Docker installation requires only Docker to be installed and running.

Can I install Starlake using Docker?​

Yes, Docker is the fastest way to get started with Starlake. Pull the image with docker pull starlakeai/starlake:latest and run commands by mounting your project directory to /starlake in the container.

Which Java version does Starlake require?​

Starlake requires Java 17 or higher. You can use either Oracle JDK or OpenJDK. Verify your version with java -version.

How do I upgrade Starlake to a newer version?​

Run starlake upgrade to fetch the latest versions from Maven Central and Sonatype Snapshots. The command lets you choose which version to install and automatically updates the configuration and downloads the new JAR files.

Can I install Starlake without Java?​

Yes. Use the Docker installation method. The Docker image includes all dependencies, so you do not need to install Java separately.