ug CLI reference

Use the Unity Gateway CLI (ug) to configure and launch coding agents. For a walkthrough, see the coding agent quickstart.

Install

Install ug, then check the installed version:

uv tool install git+https://github.com/databricks/unity-gateway
ug --version

For requirements, see the quickstart prerequisites.

Configure

Command What it does
ug configure Sign in to a Azure Databricks workspace and configure your agents using your admin's settings or guided setup.
ug configure --workspace https://your-workspace.databricks.com Configure your agents to use the workspace at the specified URL.
ug configure --agents claude,codex Configure the listed agents without prompting. To also add MCP servers, add --mcp with their full Unity Catalog names. See Add MCP servers directly.
ug configure --profile <name> --use-pat Authenticate with a personal access token instead of OAuth. First run databricks configure --host <workspace-url> to save your token in a configuration profile, then pass that profile with --profile (for example, --profile DEFAULT). The profile provides the workspace URL.

Launch an agent

These commands open the agent in your terminal, ready for your usual coding workflow.

Command What it does
ug Launch the agent selected by your admin's published workspace configuration.
ug claude Launch Claude Code through Unity Gateway.
ug codex Launch Codex through Unity Gateway.
ug gemini Launch Gemini CLI through Unity Gateway.
ug opencode Launch OpenCode through Unity Gateway.
ug copilot Launch GitHub Copilot CLI through Unity Gateway.
ug pi Launch Pi through Unity Gateway.
ug cursor Launch Cursor Agent. Model requests use your Cursor account.

For Claude Code or Codex, add --refresh to refresh workspace authentication, models, and configuration before launching. You can also pass agent-specific arguments to the launch command.

To launch an agent with a specific model, such as in a script, add --model with the model's full Unity Catalog name. This works with ug claude, ug codex, and ug copilot:

ug claude --model <full-model-name>

To choose a model interactively after the agent starts, enter /model.

MCP servers

For the server picker, other Azure Databricks MCP servers, and setup for other MCP clients, see Add tools and skills.

Command What it does
ug mcp add Select MCP servers and add their connections to your configured agents.
ug mcp list Show configured MCP servers and the status reported by each agent.
ug mcp remove Select MCP connections to remove from your agents. The servers remain in the workspace.

Add MCP servers directly

To add MCP servers without the picker, pass their full Unity Catalog names (<catalog>.<schema>.<server-name>) to --names:

ug mcp add --names system.ai.github,system.ai.slack

The names in one command must be in the same schema. Otherwise, ug returns an error. To add a server from another schema, run ug mcp add again:

ug mcp add --names "<catalog>.<schema>.<server-name>"

To add every MCP server in a schema:

ug mcp add --location "<catalog>.<schema>"

By default, ug mcp add adds servers to each of your configured agents and doesn't remove existing connections. To add servers to specific agents only, add --agents:

ug mcp add --agents claude,codex --names system.ai.github

To configure an agent and add its MCP servers in one command, use ug configure with --mcp:

ug configure --agents claude --mcp system.ai.github,system.ai.slack

Restart your agent with its usual ug command, then run ug mcp list to check the connections.

Add MCP servers for all developers (admins)

A workspace admin can add MCP servers for every developer in the workspace through a coding agent configuration. To include servers from more than one schema, list their full names in mcp_servers.names at the top level of the configuration:

{
  "mcp_servers": {
    "names": ["system.ai.github", "<catalog>.<schema>.<server-name>"]
  }
}

To include every MCP server in one schema, set unity_catalog_location to <catalog>.<schema> instead of names. For details, see mcp_servers.

Developers run ug configure to sync the servers to their agents. They can add more servers with ug mcp add, which skips servers that the workspace configuration already provides.

Skills

Command What it does
ug skills add Select published skills and download their files into local agent skill directories.
ug skills add --via mcp Connect skills from selected Unity Catalog schemas through MCP, without downloading files.
ug skills list Show the skills configured for your agents and how they were added.
ug skills remove Select downloaded skill folders to delete from your computer. Published skills remain unchanged.
ug skills remove --via mcp Remove selected schemas from the skill registry's MCP connection. Downloaded skill files are kept.

For named skills, schema selection, and project downloads, see Add tools and skills.

Manage your setup

Command What it does
ug usage Show applicable spend limits and percentage used. See Check your usage.
ug doctor Check your local installation and agent configuration, and offer fixes for problems found.
ug upgrade Install the latest Unity Gateway CLI version from GitHub.
ug export Print your admin's saved coding agent configuration as JSON for reuse.
ug revert Restore backed-up agent configuration files and clear ug's saved setup state.

Check your usage

View the Unity Gateway spend limits that apply to you.

Command What it does
ug usage Show up to five applicable spend limits, ordered from highest to lowest percentage used.
ug usage --all Show all applicable spend limits in the same order.

Each entry includes a short budget ID and one of the following labels:

Label What it shows
Monthly personal limit Your usage against the budget's per-user threshold for the month.
Monthly shared limit Combined usage across users covered by the budget against its shared threshold for the month.
Daily personal limit Your usage against the budget's per-user threshold for the day.
Daily shared limit Combined usage across users covered by the budget against its shared threshold for the day.

Your spending can count toward multiple applicable limits. A single budget can contain several limits, so multiple entries can share a budget ID.

For more information about budgets and thresholds, see Manage budgets for Unity Gateway.

Command help

Use --help to see the options for your installed version:

Command What it does
ug --help Show available commands and general options.
ug configure --help Show workspace and agent setup options.
ug mcp add --help Show options for adding MCP servers by name, schema, or agent.
ug skills add --help Show options for downloading skills or connecting them through MCP.