Skip to main content
Last updated on

Genie Code CLI

Beta

This feature is in Beta. It is an early release, and its capabilities, commands, and interfaces change frequently.

Genie Code CLI is a coding agent that runs locally in your terminal and is tuned for data and AI work on Databricks. It works like other terminal coding agents, but comes preconfigured to understand Databricks and to work naturally with your data, pipelines, models, and apps.

Because it runs on your machine, Genie Code CLI can read and edit your local files, run commands, and reach into Databricks on your behalf. It uses the Databricks CLI, including the databricks genie commands such as databricks genie ask, to discover data and answer questions about it. During Beta, model access is provided and governed through Unity Gateway, so you do not bring your own model subscription.

Requirements​

Genie Code CLI runs under your own identity, so it can only access data and perform operations that your Databricks permissions allow.

Install and set up​

  1. Install the Databricks CLI (version 1.0.0 or above) separately, if you have not already. See Install or update the Databricks CLI.

  2. Install Genie Code CLI with the command for your operating system.

    Bash
    curl -fsSL https://github.com/databricks/genie-code-cli/releases/latest/download/install.sh | bash

  3. Confirm the installation:

    Bash
    genie --version

  4. Change into your project directory and start Genie Code CLI:

    Bash
    cd my-project
    genie

  5. When prompted, select a Databricks CLI profile, or authenticate if you have not configured one. See Authentication for the Databricks CLI. Genie Code CLI uses this profile to access models through Unity Gateway. It can still use other Databricks CLI profiles to do work with other workspaces or work outside of Databricks entirely.

  6. Confirm that you trust the contents of the directory, then start prompting.

What you can do with Genie Code CLI​

Genie Code CLI can work directly with local files, discover and query your Unity Catalog data through Genie, and build and deploy Databricks assets from a single conversation in the terminal. For example:

  • Ingest and govern: "Clean up these monthly sales CSVs, load them into Unity Catalog, and show me revenue by region over time."
  • Explore your data: "Which of my catalogs has customer churn data, and what were the top drivers last quarter?"
  • Extend a pipeline: "Add a silver refunds table to my orders pipeline and backfill the last 90 days."
  • Train and serve a model: "Run this training script on Databricks and put the model behind a serving endpoint."
  • Build and ship an app: "Build a local app prototype for my customers table and deploy it as a Databricks App."

How Genie Code CLI differs from Genie Code in the workspace​

Genie Code CLI is a separate experience built for local, terminal-based work. It has its own tools, skills, and instructions, and at this time does not share them with Genie Code in the Databricks workspace. It also does not yet include all of the capabilities available in the workspace UI.

Use Genie Code CLI as a terminal-native companion when you are working locally with files, scripts, and prototypes. Continue to use Genie Code in the workspace for the richer, fully featured experience.

Set up skills and MCP servers​

You can extend Genie Code CLI with skills, MCP servers, and project instructions. If you already use Claude Code or Cursor, run /import in Genie Code CLI to import your configuration from them.

Add skills​

Genie Code CLI already comes installed with Databricks agent skills so the agent works more effectively with Databricks data and resources such as jobs, pipelines, models, and apps. These skills are in ~/.genie/skills/.system/.

To add your own skill, create a folder that contains a SKILL.md file in the standard Agent Skills format, and save it in ~/.genie/skills/. To share a skill with your team, save it in .agents/skills/ in your repository instead. Genie Code CLI also loads skills from other local folders, such as parent folders of your working directory and the root of your repository.

You can also ask Genie Code CLI to create a skill, or to convert an existing skill from another coding agent.

Genie Code CLI loads skills only from local folders. To use a skill from your Databricks workspace, such as a skill in .assistant/skills/, download it to one of these folders.

Connect MCP servers​

Use genie mcp add to connect Genie Code CLI to any MCP server, including MCP servers that are not hosted on Databricks.

To connect a remote MCP server, pass its URL and the name of an environment variable that contains an access token for it:

Bash
genie mcp add <server-name> --url <server-url> --bearer-token-env-var <env-var-name>

To connect an MCP server that runs on your machine, pass the command that starts it:

Bash
genie mcp add <server-name> -- <command> <args>

To connect a managed MCP server on Databricks, such as the Genie One MCP server:

  1. Store a Databricks access token in an environment variable:

    Bash
    export DATABRICKS_MCP_TOKEN=$(databricks auth token --profile <profile-name> | jq -r .access_token)

  2. Add the MCP server and pass the name of the environment variable. If your workspace URL includes a workspace ID, such as ?o=<workspace-id>, add it to the end of the MCP server URL.

    Bash
    genie mcp add genie_one \
      --url "https://<workspace-host>/ai-gateway/mcp-services/system.ai.genie_one_mcp" \
      --bearer-token-env-var DATABRICKS_MCP_TOKEN

  3. In the same terminal, start Genie Code CLI:

    Bash
    genie

  4. Run /mcp to confirm that the server is connected.

Add project instructions​

To give Genie Code CLI instructions that apply to every conversation in a project, such as coding conventions, catalog and schema names, or how to run tests, add an AGENTS.md file to the root of your project directory. Genie Code CLI reads this file when you start it in that directory.

Billing​

Genie Code CLI usage is billed the same as using the model directly through Unity Gateway, and appears in your Unity Gateway usage. It is not billed under Genie pricing.

To control spend, workspace admins can set budgets for Unity Gateway. See Manage budgets for Unity Gateway.

Frequently asked questions​

When should I use Genie Code CLI instead of Unity Gateway with my own coding agent?​

Use another coding agent through the ug CLI, for example ug claude, if you have already configured that agent to use Databricks agent skills and Databricks managed MCP servers, such as Genie One.

Use Genie Code CLI if you do not have this set up, or if you also want the additional tuning that Databricks applies to the agent harness so that it works better with Databricks.

How is Genie Code CLI different from other coding agents?​

Genie Code CLI works like other terminal coding agents, with these differences:

  • Preconfigured for Databricks: It includes Databricks skills, uses the Databricks CLI and Genie to discover and query your data, and is tuned with instructions for data and AI work. You do not install or configure these yourself.
  • No separate model subscription: Model access is provided and governed through Unity Gateway, and usage is billed to your Databricks account.
  • Workspace operations are governed by Databricks: Operations in your Databricks workspace run under your Databricks identity, so Unity Catalog permissions apply. Local operations, such as editing files and running commands on your machine, are not governed by Databricks.

To use another coding agent with Databricks instead, see Get started with coding agents.

Which operating systems does Genie Code CLI support?​

Genie Code CLI supports macOS, Linux, and Windows. See Install and set up.

Can I use Genie Code CLI in my IDE?​

Yes. Start Genie Code CLI from the integrated terminal of any IDE, such as Visual Studio Code, Cursor, or IntelliJ IDEA. Genie Code CLI works with the files in the directory where you start it.

How do I resume a previous conversation?​

Each time you run genie, Genie Code CLI starts a new conversation. To resume a previous conversation, use one of the following:

  • genie resume: Choose a conversation from a list.
  • genie resume --last: Resume your most recent conversation.
  • /resume: Choose a conversation from a list while Genie Code CLI is running.

How do I update Genie Code CLI?​

Genie Code CLI checks for a new version when it starts and prompts you to update. To update manually, run genie update, or run the install command for your operating system again.

How do admins govern Genie Code CLI?​

Admins govern Genie Code CLI through Unity Gateway, the same way as other coding agents. Genie Code CLI usage appears in Unity Gateway usage, and Unity Gateway budgets apply to it. See Configure coding agents and Manage budgets for Unity Gateway.

Limitations​

  • Model selection is managed by Databricks. You cannot choose a specific model. During Beta, Genie Code CLI uses GPT 5.6. The selection may differ from other Genie surfaces, and it can change over time.
  • Genie Code CLI is not billed under Genie usage, and is not impacted by Genie budgets. To control spend, set budgets for Unity Gateway. See Manage budgets for Unity Gateway.
  • Genie Code CLI supports only OAuth machine-to-machine (M2M) authentication.
  • Genie Code CLI does not support SSH tunnel sessions. To use Genie Code CLI, run it on your local machine.
  • Genie Code CLI loads skills only from local folders. It does not load skills or instructions from your workspace or from Unity Catalog.
  • If you connect an MCP server on Databricks with an access token, MCP calls fail with a 401 error after the token expires. To reconnect, exit Genie Code CLI, set the environment variable to a new token, and run genie.
On this page