CLI Setup

The CLI is used to initialize your project and configure all AscendKit services. Once your environment is linked, the remaining sections of this documentation cover individual services you can configure — authentication, email, templates, surveys, journeys, webhooks, and analytics.

Discover commands quickly

Use these help modes in terminal:

ascendkit --help
ascendkit help survey
ascendkit survey --help
ascendkit survey

Notes:

• ascendkit --help and ascendkit help both show top-level help.
• Section help works with either ascendkit help <section> or ascendkit <section> --help.

Initialize

In your app's root directory:

ascendkit init

Opens a browser window for authentication. Your credentials are saved in .ascendkit/auth.json in the current directory. The CLI automatically adds this directory to .gitignore.

After login, the CLI discovers .env and .env.local files in your project and offers to seed them with the AscendKit managed environment block. That block includes your API URL, environment keys, and an APP_URL= placeholder for your app's public hosted URL.

The CLI walks up from the current working directory until it finds an existing .ascendkit folder, so you only need to initialize once per project tree.

To check your current session:

ascendkit status

Set environment

Link your directory to an AscendKit environment. You can find your public key in the AscendKit portal under your project's environment settings, or use the CLI to browse your projects:

# List your projects and their environments
ascendkit project list
ascendkit env list --project prj_your_project_id

Then link to the environment:

ascendkit set-env pk_dev_your_public_key

This fills in the public key, secret key, and API URL in your .env/.env.local files, and preserves an APP_URL slot for auth callback configuration. All subsequent CLI commands in this directory are scoped to that project and environment.

It also writes .ascendkit/env.json so all subsequent CLI commands are scoped to that environment.

To switch environments later, find the public key with env list and run:

ascendkit set-env <public-key>

Verify setup

ascendkit verify

Checks connectivity to all services (Auth, Email, Content, Surveys, Journeys) and reports their status.

Log out

ascendkit logout

Clears the local .ascendkit/auth.json credentials.

Environment variables

After ascendkit set-env completes, the CLI populates your .env/.env.local files with the keys your SDK needs. See Installation — Environment variables for the full reference table.

The SDK reads these environment variables automatically at runtime, so you don't need to pass them as constructor arguments or component props. The Next.js Integration page shows both patterns if you need explicit configuration.

We recommend setting APP_URL to the origin where your app is running — http://localhost:3000 for local dev, or https://app.yourdomain.com for production. The SDK can infer the origin from incoming requests when APP_URL is blank, but setting it explicitly avoids "Invalid origin" errors with social login callbacks.

Next steps

Once your environment is linked, configure the services your app needs:

• Projects — create projects and inspect available environments
• Environments — switch environments and manage environment variables
• Auth Configuration — sign-in methods, OAuth providers, email verification, waitlist
• Email Identity — sender address and domain verification
• Email Templates — customize transactional email content
• Surveys — NPS, CSAT, and custom surveys with distribution tracking
• User Journeys — automated lifecycle flows triggered by user events
• Webhooks — real-time event notifications to your server
• Campaigns — targeted email campaigns with scheduling and analytics
• User Import & Migration — import users from Clerk and set up migration journeys
• Analytics — track user behavior from client and server