Genie Code CLI
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. Genie Code CLI uses models that Databricks provides, so you don't need to bring your own model subscription. You manage access and budgets the same way as for Genie Code. See Billing and budgets.
Requirements
- A Databricks workspace in a region where Genie Code CLI is available. Model and feature availability vary by region. See Regional availability.
- Partner-powered AI features enabled for both the account and workspace. See Partner-powered AI features.
- Unity Catalog enabled for your workspace. See Enable a workspace for Unity Catalog.
- The Databricks CLI version 1.0.0 or above, installed separately. Genie Code CLI uses it to authenticate and to run the
databricks geniecommands. See Install or update the Databricks CLI.
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
-
Install the Databricks CLI (version 1.0.0 or above) separately, if you have not already. See Install or update the Databricks CLI.
-
Install Genie Code CLI with the command for your operating system.
- Linux or macOS
- Windows
Bashcurl -fsSL https://github.com/databricks/genie-code-cli/releases/latest/download/install.sh | bashRun the following in PowerShell:
PowerShellpowershell -ExecutionPolicy Bypass -c "irm https://github.com/databricks/genie-code-cli/releases/latest/download/install.ps1 | iex" -
Confirm the installation:
Bashgenie --version -
Change into your project directory and start Genie Code CLI:
Bashcd my-projectgenie -
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 for model access and billing. It can still use other Databricks CLI profiles to do work with other workspaces or work outside of Databricks entirely.
-
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
refundstable 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
customerstable 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:
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:
genie mcp add <server-name> -- <command> <args>
To connect a managed MCP server on Databricks, such as the Genie One MCP server:
-
Store a Databricks access token in an environment variable:
Bashexport DATABRICKS_MCP_TOKEN=$(databricks auth token --profile <profile-name> | jq -r .access_token) -
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.Bashgenie mcp add genie_one \--url "https://<workspace-host>/ai-gateway/mcp-services/system.ai.genie_one_mcp" \--bearer-token-env-var DATABRICKS_MCP_TOKEN -
In the same terminal, start Genie Code CLI:
Bashgenie -
Run
/mcpto 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.
Regional availability
Genie Code CLI is a Designated Service. Its availability depends on your workspace's region and on the Enforce data processing within workspace Geography for Designated Services setting. Cross-Geo processing is enabled by default for workspaces outside the US and EU that don't have the compliance security profile enabled. If cross-Geo processing is disabled, Genie Code CLI might not be available in your workspace. For availability in each Geo, see Availability of Designated Services in each Geo.
Genie Code CLI isn't available in regions where Genie pay-as-you-go billing isn't available: Azure West Central US and Qatar Central, AWS Asia Pacific (Jakarta), and government regions.
Web search
Web search has additional requirements:
- Web search has the same requirements as web search in Genie Code, including the Web search in Genie Code and Genie One preview.
- Unlike web search in Genie Code, web search in Genie Code CLI isn't available in workspaces with the compliance security profile.
When web search isn't available, Genie Code CLI can still access the internet by running shell commands such as curl.
Billing and budgets
Genie Code CLI is billed the same way as Genie Code, using Genie pay-as-you-go pricing. It shares the free monthly usage that each user receives for Genie products. Genie Code CLI usage is tracked through Unity Gateway.
Budgets and cost controls for Genie Code CLI are managed alongside other Genie products, and Genie Code CLI usage counts toward the same Genie budget. See Manage budgets and cost controls for Genie.
Genie Code CLI usage appears in the system.billing.usage system table with usage_metadata.genie.surface set to GENIE_CODE_CLI. See Monitor and understand your Genie cost.
For current pricing and the free usage amount, see the Databricks pricing page.
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: Genie Code CLI uses models that Databricks provides, and usage is billed to your Databricks account the same way as Genie Code.
- 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?
Genie Code CLI usage is tracked through Unity Gateway, and admins manage its budgets alongside other Genie products. See Manage budgets and cost controls for Genie.
Limitations
- Genie Code CLI supports only OAuth user-to-machine (U2M) authentication, using a Databricks CLI profile created with
databricks auth login. OAuth machine-to-machine (M2M) authentication and personal access tokens aren't supported. - 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
401error after the token expires. To reconnect, exit Genie Code CLI, set the environment variable to a new token, and rungenie.