Skip to main content

Quick Start

Get your first Qumra app running in under 5 minutes.

Prerequisites​

Before you begin, make sure you have:

  • Node.js 20+ installed (download)
  • npm (comes with Node.js)
  • A Qumra account (sign up)

Step 1: Install the Qumra CLI​

Install the CLI globally to access all Qumra development commands:

npm install -g @qumra/cli

Verify the installation:

qumra version

Step 2: Login to Qumra​

Authenticate the CLI with your Qumra account:

qumra user login

This opens your browser for authentication. Once you approve the login, the CLI stores your session token locally.

Login Required

You must complete this step before running any other qumra commands. The CLI requires an active session to communicate with the Qumra platform.

Step 3: Create Your App​

You can scaffold a new Qumra app using either approach:

Use the Qumra CLI interactive prompts:

qumra app init

The CLI will ask you for:

  • App name -- The display name for your app
  • App slug -- A URL-friendly identifier (auto-generated from name)
  • Description -- A short description of what your app does

After answering the prompts, the CLI creates a new directory with the full app scaffold.

Step 4: Configure Environment​

Navigate into your app directory and set up environment variables:

cd my-app

Create a .env file in the project root with the following variables:

.env
# Required -- from Qumra Partner Dashboard
QUMRA_API_KEY=your_api_key_here
QUMRA_API_SECRET=your_api_secret_here

# Required -- database connection
DATABASE_URL="file:./dev.db"

# Optional -- defaults shown
QUMRA_APP_URL=http://localhost:3000
PORT=3000
Where to find your API credentials

Your QUMRA_API_KEY and QUMRA_API_SECRET are available in the Qumra Partner Dashboard under your app settings. These are generated automatically when you create an app via the CLI.

Step 5: Run Database Migrations​

Set up the local SQLite database with Prisma:

npx prisma migrate deploy

This applies all pending migrations and creates the dev.db file in your prisma/ directory.

Step 6: Start Development​

Launch the development server:

qumra app dev

You should see output similar to:

> App server started successfully!

  Dashboard     -> http://localhost:3000
  App URL       -> https://your-store.qumra.store/admin/apps/my-app
  Auth Callback -> http://localhost:3000/auth/callback

Your app is now running locally and accessible through the Qumra admin panel.

Select a Dev Store

During development, you will be prompted to select a development store. Choose the store you want to test your app with. You can change this at any time by restarting the dev server.

What's Next​

Now that your app is running, explore these guides to build out your functionality: