Skip to main content

App development

This page is the CLI and workflow reference for Databricks Apps and AppKit. It covers adding plugins, scaffolding, deploying, managing, and troubleshooting your app.

Each command below shows a common invocation, its full set of flags, and a table describing each. Run databricks <command> --help for current flag behavior, since the CLI is the source of truth.

Local setup

databricks apps init writes a .env file in the project root with your CLI profile and the connection values for the resources you chose. AppKit reads it for local connections to Databricks resources. .env.example lists the connection keys with placeholder values (with DATABRICKS_HOST in place of the profile); copy it to .env and fill it in only when you start from a project that has no .env, such as a fresh clone.

Example .env (abbreviated) for an app with Lakebase Postgres:

DATABRICKS_CONFIG_PROFILE=<profile>
PGHOST=<endpoint-host>
PGDATABASE=<database-name>
LAKEBASE_ENDPOINT=projects/<project>/branches/production/endpoints/primary
PGPORT=5432
PGSSLMODE=require

The default AppKit template uses pnpm: apps init installs dependencies with pnpm, and the project scripts call it, so run the app with pnpm run dev. To scaffold an npm project instead, pass --package-manager npm to apps init and use npm run dev.

If your app uses Lakebase, run databricks apps deploy once before pnpm run dev, so the app's service principal creates and owns the schema. If you created the Lakebase project, your identity already has the access it needs locally. Teammates need a Postgres role on the branch, which the project creator can add. See Lakebase Development for the full local access workflow.

For testing against production data without redeploying, see the remote bridge.

Add a plugin

To add a plugin to an existing app, import and register it in createApp in server/server.ts:

import { createApp, genie, lakebase, server } from "@databricks/appkit";

const AppKit = await createApp({
  plugins: [server(), lakebase(), genie()],
});

Then regenerate appkit.plugins.json with the updated resource requirements (the template's sync script runs appkit plugin sync --write):

pnpm run sync

This runs automatically before the template's dev and build scripts. Commit the updated appkit.plugins.json alongside your code. databricks apps validate reads it; the resources themselves are declared in databricks.yml (see App configuration).

See the AppKit plugins reference for configuration options for each plugin, or Creating custom plugins to add your own.

Discover plugins

List available plugins and their required resource fields:

databricks apps manifest
OptionDescription
--branchGit branch or tag (for GitHub templates, mutually exclusive with --version)
--templateTemplate path (local directory or GitHub URL)
--versionAppKit version for default template (default: main, use 'latest' for main branch)
--debugenable debug logging
--output, -ooutput type: text or json (default text)
--profile, -p~/.databrickscfg profile
--target, -tbundle target to use (if applicable)
--varset values for variables defined in bundle config. Example: --var="key=value"

Scaffold options

Use databricks apps init to scaffold a new AppKit project. The Apps Quickstart shows the fast path. Use these options for non-interactive or advanced scaffolding.

databricks apps init --name my-app
OptionDescription
--auth-modeDefault resource auth mode: obo (on behalf of the user) or sp (service principal). With obo, resources that cannot be accessed on behalf of the user use sp. Prompts if not provided in interactive mode, otherwise sp.
--branchGit branch or tag (for GitHub templates, mutually exclusive with --version)
--deployDeploy the app after creation
--descriptionApp description
--featuresFeatures/plugins to enable (comma-separated, as defined in template manifest)
--output-dirDirectory to write the project to
--package-managerNode.js package manager (pnpm, npm; default: inferred from template)
--runRun the app after creation (none, dev, dev-remote)
--setSet resource values (format: plugin.resourceKey.field=value, can specify multiple)
--skip-installSkip installing project dependencies (e.g. npm install / uv sync). Cannot be combined with --run.
--templateTemplate path (local directory or GitHub URL)
--versionAppKit version to use (default: auto-detected, use 'latest' for main branch)
--debugenable debug logging
--output, -ooutput type: text or json (default text)
--profile, -p~/.databrickscfg profile
--target, -tbundle target to use (if applicable)
--varset values for variables defined in bundle config. Example: --var="key=value"

Passing --name makes apps init non-interactive, so every required resource field must be set with --set. Run databricks apps manifest to see available plugins and their --set keys. App names must be lowercase, hyphenated, and 26 characters or fewer.

--auth-mode sets how the app accesses its resources by default: obo (on behalf of the signed-in user, falling back to the service principal for resources that can't be accessed that way) or sp (the app's service principal, the non-interactive default). Override it for one resource with --set <plugin>.<resource-key>.authMode=obo|sp|both. --auth-mode and --package-manager need Databricks CLI v1.20.0 or later.

Environment configuration

Local (pnpm run dev): variables from .env in the project root.

Deployed: variables from app.yaml env entries. Use value for plain strings and valueFrom for resource bindings:

env:
  - name: LAKEBASE_ENDPOINT
    valueFrom: postgres
  - name: DATABRICKS_WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: APP_LOG_LEVEL
    value: info

Resources referenced by valueFrom must be declared as app resources: in databricks.yml for bundle deploys, or in the app's configuration in the workspace UI. See App configuration for the full resource list.

Pre-deploy checklist

Before deploying to production:

  • App binds to 0.0.0.0 on DATABRICKS_APP_PORT
  • app.yaml command uses array syntax (no shell strings)
  • No files larger than 10 MB in the project
  • Secrets use valueFrom (never value)
  • All required resources are declared (in databricks.yml or the app's workspace configuration), including SELECT on tables your analytics queries read: the build's type generation runs as the app's service principal
  • databricks apps validate succeeds (--skip-tests skips tests for a faster run)
  • pnpm run build succeeds locally

Validate

Run validation from your app project directory before deploying:

databricks apps validate --profile $DATABRICKS_PROFILE

Validation runs a build, typecheck, and lint. Pass --skip-tests for a faster run.

Deploy

databricks apps deploy
OptionDescription
--auto-approveSkip interactive approvals that might be required for deployment.
--deployment-idThe unique id of the deployment.
--forceForce-override Git branch validation.
--git-branchGit branch to deploy from.
--git-commitGit commit SHA to deploy from.
--git-source-code-pathRelative path to the app source code within the Git repository. Defaults to the repository root.
--git-tagGit tag to deploy from.
--jsoneither inline JSON string or @path/to/file.json with request body (default JSON (0 bytes))
--modeThe mode of which the deployment will manage the source code. Supported values: [AUTO_SYNC, SNAPSHOT]
--no-waitdo not wait to reach SUCCEEDED state
--skip-testsSkip running tests during validation (default true)
--skip-validationSkip project validation (build, typecheck, lint)
--source-code-pathThe workspace file system path of the source code used to create the app deployment.
--timeoutmaximum amount of time to reach SUCCEEDED state (default 20m0s)
--debugenable debug logging
--output, -ooutput type: text or json (default text)
--profile, -p~/.databrickscfg profile
--target, -tbundle target to use (if applicable)
--varset values for variables defined in bundle config. Example: --var="key=value"

In your project directory, without an app name, the CLI runs the same validation as databricks apps validate (build, typecheck, lint), uploads the project, and starts the app. Pass --skip-validation to skip validation. No --source-code-path is needed when deploying from a scaffolded AppKit project. With an app name, the CLI uses API deploy instead of the project deploy flow, and deploys the source you name.

When you pass an app name, pick one source: a workspace folder with --source-code-path, or a Git source with exactly one of --git-branch, --git-tag, or --git-commit (plus --git-source-code-path for a subfolder). The CLI rejects --source-code-path combined with a --git-* flag, and more than one Git ref.

Verify the deployment

Check that the app deployed successfully:

databricks apps get my-app -o json
OptionDescription
--debugenable debug logging
--output, -ooutput type: text or json (default text)
--profile, -p~/.databrickscfg profile
--target, -tbundle target to use (if applicable)
--varset values for variables defined in bundle config. Example: --var="key=value"
Example output
{
  "name": "my-app",
  "url": "https://my-app-1234567890.us-west-2.databricksapps.com",
  "description": "A Databricks App powered by AppKit",
  "compute_size": "MEDIUM",
  "app_status": {
    "message": "App has status: App is running",
    "state": "RUNNING"
  },
  "compute_status": {
    "message": "App compute is running.",
    "state": "ACTIVE"
  },
  "active_deployment": {
    "deployment_id": "a1b2c3d4e5f6",
    "source_code_path": "/Workspace/Users/[email protected]/.bundle/my-app/default/files",
    "status": {
      "message": "App started successfully",
      "state": "SUCCEEDED"
    }
  },
  "resources": [
    {
      "name": "postgres",
      "postgres": {
        "branch": "projects/my-project/branches/production",
        "database": "projects/my-project/branches/production/databases/db-abc123",
        "permission": "CAN_CONNECT_AND_CREATE"
      }
    }
  ],
  "service_principal_client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

View logs:

databricks apps logs my-app
OptionDescription
--follow, -fContinue streaming logs until interrupted.
--tail-linesNumber of recent log lines to show before streaming. Set to 0 to show everything. (default 200)
--timeoutMaximum time to stream when --follow is set. 0 disables the timeout.
--searchSend a search term to the log service before streaming.
--sourceRestrict logs to APP and/or SYSTEM sources.
--output-fileOptional file path to write logs in addition to stdout.
--debugenable debug logging
--output, -ooutput type: text or json (default text)
--profile, -p~/.databrickscfg profile
--target, -tbundle target to use (if applicable)
--varset values for variables defined in bundle config. Example: --var="key=value"
Example log output
[SYSTEM] [INFO] Starting Databricks Apps runtime...
[BUILD] [INFO] Starting deployment a1b2c3d4e5f6...
[BUILD] [INFO] Downloading source code from /Workspace/Users/.../src/a1b2c3d4e5f6
[BUILD] [INFO] Installing dependencies...
[BUILD] Packages: +766
[BUILD] Done in 19s using pnpm v11.0.8
[BUILD] [INFO] Dependencies installed successfully.
[BUILD] [INFO] Running build script pnpm run build:server && pnpm run build:client
[BUILD] ✔ Build complete in 90ms
[BUILD] ✓ built in 1.60s
[BUILD] [INFO] Build completed successfully.
[BUILD] [INFO] Starting app with command: [pnpm run start]
[BUILD] [INFO] Deployment successful
[APP] [appkit:server] Server running on http://0.0.0.0:8000
[APP] [appkit:server] Mode: production (static)

Roll back

Apps has no single rollback action. To roll back, redeploy an earlier version: for a Git-backed app, deploy the earlier tag or commit (for example databricks apps deploy my-app --git-commit <commit-sha>, or --git-tag for a release tag); for a workspace-source app, restore the earlier source to the folder and redeploy it. databricks apps list-deployments my-app lists past deployments. See Roll back to a previous version.

Managing apps

databricks apps stop my-app
databricks apps start my-app
databricks apps delete my-app

apps stop options

OptionDescription
--no-waitdo not wait to reach STOPPED state
--timeoutmaximum amount of time to reach STOPPED state (default 20m0s)
--debugenable debug logging
--output, -ooutput type: text or json (default text)
--profile, -p~/.databrickscfg profile
--target, -tbundle target to use (if applicable)
--varset values for variables defined in bundle config. Example: --var="key=value"

apps start options

OptionDescription
--no-waitdo not wait to reach ACTIVE state
--timeoutmaximum amount of time to reach ACTIVE state (default 20m0s)
--debugenable debug logging
--output, -ooutput type: text or json (default text)
--profile, -p~/.databrickscfg profile
--target, -tbundle target to use (if applicable)
--varset values for variables defined in bundle config. Example: --var="key=value"

apps delete options

OptionDescription
--auto-approveSkip interactive approvals for deleting resources and files
--force-lockForce acquisition of deployment lock.
--debugenable debug logging
--output, -ooutput type: text or json (default text)
--profile, -p~/.databrickscfg profile
--target, -tbundle target to use (if applicable)
--varset values for variables defined in bundle config. Example: --var="key=value"

apps delete prompts for confirmation. Pass --auto-approve in CI to skip the prompt.

CI/CD

For automated deploys in CI, set DATABRICKS_HOST and DATABRICKS_TOKEN (or use OAuth with DATABRICKS_CLIENT_ID and DATABRICKS_CLIENT_SECRET):

DATABRICKS_HOST=https://<workspace>.cloud.databricks.com \
DATABRICKS_TOKEN=dapi... \
databricks apps deploy

Or use a pre-configured profile:

databricks apps deploy --profile ci-profile

See the Databricks CLI authentication docs for all auth methods. For GitHub Actions, CI/CD with GitHub Actions uses workload identity federation, so the workflow stores no secret.

Troubleshooting

For additional troubleshooting, see Deploy apps and the AppKit remote bridge for local connection issues.

  • App fails to deploy: Check logs for error messages, validate app.yaml syntax, and verify that secrets and environment variables in the env section resolve properly. Confirm all dependencies are included or installed.
  • 401 errors (authentication): Verify your token is valid, hasn't expired, and includes the required OAuth scopes. For a user (U2M) profile, run databricks auth token --profile <PROFILE> to check it. Your token's scopes must be a superset of the scopes configured for the app's user authorization.
  • 403 errors (permission denied): Verify you have CAN USE permission on the app. Insufficient OAuth scopes can also cause 403s even with valid permissions.
  • Build fails in type generation: On deploy, the build runs AppKit's type generation as the app's service principal, which describes each analytics query. If it can't read a table, the deploy fails with Error building app, and AppKit may report the failed queries as SQL errors. Add the table as an app resource with SELECT (a uc_securable with securable_type: TABLE).
  • Deploy or start fails on OAuth scopes: Workspace admins can restrict which user authorization scopes apps may request. Remove scopes that aren't allowed from user_api_scopes. See Restrict user authorization scopes.
  • 404 errors (app not found): Verify the app name and workspace URL are correct, the app is deployed and running, and the endpoint path exists.
  • Git deployment fails: For private repositories, verify the app's service principal has a Git credential configured. If deploying through CLI/API/DABs, create the app first, then add the Git credential.

AppKit docs

Access the AppKit API reference, component docs, and plugin docs from your project directory. pnpm exec runs the AppKit version your project installed:

pnpm exec appkit docs                        # browse the documentation index
pnpm exec appkit docs --full                 # full index with all API entries
pnpm exec appkit docs "<section-or-./docs/path.md>"  # view a section or doc file

Run without arguments to browse the index. Useful when building with an AI coding assistant. Point it here instead of guessing API shapes, or view the AppKit reference on this site.

Where to next

Browse the templates catalog to start building, or add capabilities to your app: Lakebase Postgres for persistent storage or Agent Bricks for AI features.

Databricks Developer Hub

Ready to ship your next agentic app in minutes?

Read docs