Initialize and configure AscendKit in your project.

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.

Diagnose setup

ascendkit doctor

Checks local login state, active environment context, API key resolution, auth settings, email domain status, webhook configuration, and SDK/API compatibility signals available from the API.

For more detail on any command:

ascendkit set-env pk_dev_your_public_key --debug
ascendkit doctor --verbose

Debug and verbose output includes resolved project, environment, API host, client request ID, response status, and failure reason. Secrets and tokens are redacted.

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.

Projects and environments

A project holds your application; an environment is one deployment of it (development, preview, production). Every new project gets a development environment automatically, and each environment has its own public key — which is why a token issued in development will not verify in production.

Manage projects

ascendkit project list
ascendkit project create \
  --name "Acme App" \
  --description "Customer onboarding app" \
  --services auth,content,surveys
ascendkit project show prj_abc123

Select the active environment

The active environment is stored in .ascendkit/env.json. The CLI walks up from the current working directory until it finds the nearest .ascendkit folder, so commands work from anywhere inside your project tree.

ascendkit env list --project prj_abc123
ascendkit set-env <public-key>
ascendkit environment show

set-env updates the local CLI context only. If .env, .env.local, or .env.example are present in the project tree, selection also syncs the AscendKit-managed keys into those files — which is the usual reason a key changes without you editing it.

Environment variables

Runtime settings are stored as key-value pairs on the environment and appear on the environment settings page in the portal. These are distinct from the .env keys above: those configure the SDK, these are values your app reads at runtime.

ascendkit vars list
ascendkit vars set API_BASE_URL https://api.example.com
ascendkit vars remove SUPPORT_EMAIL

Key rules: keys must start with a letter or underscore, may contain letters, digits, underscores and hyphens, and all values are stored as strings.

Update and promote

ascendkit environment update --name "Preview" --description "Customer QA environment"
ascendkit environment promote --target production

Promotion copies configuration from one environment to another, so you can verify auth settings, templates, and journeys in preview before they reach production.

Next steps

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

  • 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