Skip to main content

Setup Guide - Dev Assist for Gemini CLI

This guide explains how to deploy cx-devassist to developer machines using Gemini CLI's enterprise system-settings capabilities.

Using system settings, organizations can centrally configure Gemini CLI's extension and MCP policy so that the cx-devassist extension, once installed, runs with organization-approved defaults rather than per-developer configuration. Gemini CLI does not have a settings key that installs an extension for a developer the first time Gemini CLI starts — the extension must still be installed on each machine (see Step 1 — Install the Extension on Developer Machines). System settings then apply on top of that installed extension. System settings can be delivered through several methods — described in Deployment Methods. Gemini CLI merges settings across scopes by key: the highest-precedence scope wins per key, rather than one scope entirely replacing another.

By default, developers authenticate to Checkmarx One using either Browser sign-in (OAuth) or an API key. With browser sign-in, developers provide their Checkmarx One URL and tenant during initial authentication; these values are remembered for subsequent use. With API key authentication, the API key contains the URL and tenant information and should be distributed through your organization's approved secret-management process.

For organizations using Browser sign-in (OAuth), the Checkmarx One URL and tenant can also be preconfigured so developers do not need to enter them during initial authentication. This requires an internal fork or mirror of the Checkmarx repository, as described in Optional — Preconfigure the Checkmarx One URL and Tenant.

Important

There is no separate system-settings field for onboarding. The Checkmarx One URL and tenant must be baked into the extension bundle your machines install from — the extension deliberately does not read onboarding values from environment variables, ~/.checkmarx, or any other out-of-tree path.

Prerequisites

Before deploying cx-devassist, ensure developer machines meet the extension's host requirements (see gemini-cli-devassist.md):

Requirement

Windows

macOS

Linux

Git for Windows (POSIX sh for hooks)

Required

—

—

Python 3

Required

Required

Required

Gemini CLI

Installed and managed by your organization

Same

Same

Windows: Verify that sh is available by running sh --version. If Git for Windows is installed but sh is not recognized, ensure that the Git bin directory is included in PATH.

Deployment Methods

Gemini CLI reads enterprise policy from a system settings file, split into two files that merge with the rest of the settings chain:

File

Role

system-defaults.json

Baseline defaults (lowest precedence within the system layer)

settings.json

Overrides — highest precedence of all scopes ("System Overrides")

Precedence (scalar values), lowest to highest:

  1. System Defaults (system-defaults.json)

  2. User Settings (~/.gemini/settings.json)

  3. Workspace Settings (<project>/.gemini/settings.json)

  4. System Overrides (settings.json)

Array settings (for example, includeDirectories) concatenate across scopes; object settings (for example, mcpServers) merge by key, with the highest-precedence scope's definition winning per key.

Gemini CLI's scopes are additive — a workspace setting and a system override can both be in effect at once, merged key by key. What is deliberately not overridable through this file is a separate, cloud-hosted layer called Enterprise Admin Controls (see below) — that layer is immutable at the local level even to someone with system-settings file access.

The system settings file can be delivered through any of the following mechanisms:

Method

Platform

Location

File-based

Linux

/etc/gemini-cli/settings.json

File-based

Windows

C:\ProgramData\gemini-cli\settings.json

File-based

macOS

/Library/Application Support/GeminiCli/settings.json

Environment override

All platforms

GEMINI_CLI_SYSTEM_SETTINGS_PATH points at an alternate location

Cloud-hosted

All platforms

Enterprise Admin Controls Management Console

Note: GEMINI_CLI_SYSTEM_SETTINGS_PATH is a local environment variable — a user could in principle unset it. For policy that must remain immutable at the local level even against that, use the cloud-hosted Enterprise Admin Controls console instead of (or in addition to) the JSON file. Official reference: docs/cli/enterprise.md and docs/admin/enterprise-controls.md in google-gemini/gemini-cli — check these against your installed CLI version, since exact keys can change between releases.

Procedure

Step 1 — Install the Extension on Developer Machines

Gemini CLI has no settings key that installs an extension for a developer automatically. Each machine needs the extension installed at least once, pointed at the official repository (or your internal fork — see Optional — Preconfigure the Checkmarx One URL and Tenant):

gemini extensions install https://github.com/Checkmarx/cx-agentic-ai.git

Choose the delivery path that matches your organization's provisioning model:

  • Base image / golden image — run the install command as part of image build. Best for VDI, managed cloud dev environments, or any fleet you re-image regularly.

  • Provisioning script — push the same command once per machine through your existing device-management tooling (Intune script deployment, Jamf policy script, Ansible/config-management run, and so on).

  • Manual, developer-run — publish the install command in your onboarding docs and have developers run it themselves; combine with Step 2 to still enforce MCP/tool policy once installed.

  • Local-path install (offline / air-gapped) — if machines can't reach GitHub, distribute the repository as a local path (network share, synced repo copy): gemini extensions install "C:\path\to\cx-agentic-ai"

Restart Gemini CLI (or run /extensions reload) so hooks, MCP, and skills are picked up. Verify with /extensions list and /skills list — you should see extension cx-devassist and three skills (cx-cli-setup, cx-devassist-asca, cx-devassist-sca).

Step 2 — Configure Gemini CLI System Settings

Once the extension is installed, system settings can restrict which MCP servers and tools are usable, so managed machines run with organization-approved defaults:

{
  "mcp": {
    "allowed": ["Checkmarx"]
  }
}

This configuration:

  • mcp.allowed — Restricts MCP usage to the Checkmarx server only, blocking developers from wiring up arbitrary other MCP servers on managed machines.

Omit mcp.allowed if you don't need that restriction — the Checkmarx MCP server works without it as soon as the extension is installed.

The Checkmarx MCP server (Checkmarx) is declared inside the installed extension's gemini-extension.json as a local-command server (sh .../hooks/cx_run.sh mcp bridge). Gemini CLI's requiredMcpServers key (which force-injects an MCP server regardless of user config) supports remote transport only (sse/http), so the Checkmarx MCP server cannot be delivered that way — it arrives only through the installed extension itself.

Step 3 — Deploy the Settings

Deploy the system settings file to the path for your OS (see Deployment Methods), or point at a custom path via GEMINI_CLI_SYSTEM_SETTINGS_PATH if your rollout mechanism sets environment variables centrally. Administrator or elevated permissions are required to deploy the file.

For policy that must survive even someone editing the system settings file locally, use the cloud-hosted Enterprise Admin Controls console instead — it layers on top of everything above rather than replacing it.

Step 4 — Verify the Deployment

Verify the deployment on a test machine before rolling it out broadly.

  1. Run gemini extensions list — confirm cx-devassist is installed and shows hooks + MCP.

  2. Confirm system settings are in effect (check the effective settings the CLI reports, or inspect the deployed system-path file directly).

  3. Trigger first-use authentication — for example, attempt a scannable file write that hits the security gate, or run /cx-cli-setup.

  4. If authentication is required, select your organization's authentication method:

    • Browser sign-in (OAuth) — Enter the Checkmarx One URL and tenant provided by your organization, then complete authentication in the browser.

    • API key — Provide the Checkmarx One API key according to your organization's authentication process.

  5. When using Browser sign-in (OAuth), confirm the gate/skill uses the pre-filled --base-auth-uri and --tenant values — the developer should not be prompted for URL or tenant.

  6. Complete login in the browser, then confirm cx auth validate succeeds.

Audit logs, if enabled, are written to:

~/.checkmarx/agent-logs/gemini-cli/checkmarx-devassist.jsonl

Optional — Preconfigure the Checkmarx One URL and Tenant

When using Browser sign-in (OAuth), you can preconfigure the Checkmarx One URL and tenant so developers do not need to enter these values during initial authentication.

This requires maintaining an internal fork or mirror of the Checkmarx repository.

Important: With the standard deployment, the extension is installed directly from the official Checkmarx repository, so Checkmarx updates can be received directly. If your organization uses an internal fork or mirror to preconfigure the Checkmarx One URL and tenant, your organization administrator must keep the internal repository synchronized with updates from the official Checkmarx repository.

Step 1 — Create an Internal Fork or Mirror

  1. Fork or mirror Checkmarx/cx-agentic-ai into a repository controlled by your organization, for example YourOrg/cx-agentic-ai.

  2. Create a dedicated branch or tag for the managed deployment, for example mdm-v1 or release/mdm-2026-08.

  3. Do not install from upstream master unless you maintain that branch — upstream updates will replace your onboarding configuration.

gemini-extension.json lives at the repository root — this is a hard requirement of Gemini CLI's extension loader, so install/link the repository root directly, not a subdirectory.

Step 2 — Configure the Checkmarx One URL and Tenant

In the internal repository, edit:

config/cx-onboarding.properties

Uncomment and set both values (both are required for pre-fill to work):

cx_base_auth_uri=https://eu.ast.checkmarx.net
cx_tenant=your-org-tenant

Use the Checkmarx One base authentication URL for your region or your on-premises deployment.

You can find the tenant in Checkmarx One under Settings → Identity and Access Management → General Settings (Display Name), or in the Checkmarx One welcome email.

Value formats and common regions

Key

Format

Example

cx_base_auth_uri

https://<host>[:port] — no path, query, userinfo, or trailing slash

https://eu.ast.checkmarx.net

cx_tenant

Starts with alphanumeric; then letters, digits, ., _, - only; max 64 characters

acme-corp

Region

URL

US

https://ast.checkmarx.net

US2

https://us.ast.checkmarx.net

EU

https://eu.ast.checkmarx.net

ANZ

https://anz.ast.checkmarx.net

India

https://ind.ast.checkmarx.net

Use your on-premises URL if applicable.

If either value is missing or invalid, the extension falls back to requesting the information from the developer rather than blocking authentication.

Commit and push the change to the branch or tag you will install/pin from.

Step 3 — Point Your Rollout at the Internal Repository

Update whichever delivery path you chose in Step 1 — Install the Extension on Developer Machines of the main procedure to reference the internal repository and the branch or tag used for the deployment:

gemini extensions install https://github.com/YourOrg/cx-agentic-ai.git --ref mdm-v1

--ref pins to the branch/tag/commit you control — recommended, so an upstream update to a branch you don't own can't silently change what's installed. Confirm the exact flag against gemini extensions install --help on your installed version, since flags can change between Gemini CLI releases.

Step 4 — Deploy the Updated Rollout

Redeploy through the same delivery path described in Step 1 — Install the Extension on Developer Machines.

Step 5 — Verify Preconfigured Onboarding

On a test machine:

  1. Confirm that cx-devassist is installed (gemini extensions list).

  2. Trigger first-use authentication.

  3. Select Browser sign-in (OAuth) if authentication is required.

  4. Verify that the authentication flow uses the configured Checkmarx One URL and tenant without asking the developer to provide them.

  5. Complete browser authentication, then confirm cx auth validate succeeds.

Maintain the Internal Repository

When Checkmarx publishes an updated version:

  1. Merge or cherry-pick the upstream Checkmarx changes into the internal repository.

  2. Re-apply your cx-onboarding.properties values if the merge overwrote them.

  3. Test the updated extension on a pilot machine: gemini extensions update cx-devassist (or reinstall pinned to a new ref), then /extensions reload.

  4. Tag a new ref (for example, mdm-v2) and update the ref in your install command/image/script if you pin by tag.

  5. Redeploy through your chosen delivery path, or rely on --auto-update if you enabled it against a maintained branch (not a fixed release tag).

Do not edit config/cx-onboarding.properties directly in a developer's installed extension directory (~/.gemini/extensions/cx-devassist/...). Installed extension files can be overwritten during an update.

Optional — Enterprise Policy Controls

Gemini CLI system settings can also restrict MCP servers, tools, and other Gemini CLI behavior. These controls are not required to deploy cx-devassist.

Restrict MCP Servers and Tools

Setting

Purpose

mcp.allowed

Allowlist of MCP server names permitted to run; unlisted servers (from user/workspace config) are blocked

mcpServers

Registers/overrides MCP servers by name; merges by key across scopes — use only if you need to override the extension's own MCP server definition (uncommon)

mcp.excludeTools / per-server includeTools / excludeTools

Fine-grained tool restriction within an MCP server

tools.core

Allowlist built-in Gemini CLI tools org-wide (tools.exclude is the deprecated blocklist form)

Because cx-devassist uses the Checkmarx MCP server, ensure any MCP allowlist used by your organization permits it (server name Checkmarx).

Additional Security Controls

For policy that must be immutable at the local level — not just a default a user with system-settings access could edit — use the cloud-hosted Enterprise Admin Controls management console. This is a separate control plane from the JSON file and is not required for the Checkmarx deployment.

Use these settings according to your organization's Gemini CLI security policy. They are not Checkmarx-specific requirements.

For the complete set of available controls and their syntax, see docs/cli/enterprise.md and docs/admin/enterprise-controls.md in google-gemini/gemini-cli.

API Key Authentication

API key authentication does not use cx-onboarding.properties. The API key contains the Checkmarx One URL and tenant information, so these values do not need to be preconfigured in the extension.

If your organization uses API key authentication, distribute the Checkmarx One API key through your organization's approved secret-management process, separately from the system-settings deployment. No onboarding file is involved.

Developers select API key as the authentication method during setup.

Troubleshooting

Symptom

Likely cause

Action

gemini extensions list doesn't show cx-devassist

Install never ran on this machine, or ran against the wrong path

Re-run the install command from Step 1 against the repository root

/skills list shows "No skills available"

UTF-8 BOM in SKILL.md, or installed from the wrong directory

Re-save SKILL.md files as UTF-8 without BOM; reinstall from the repository root

Developer is prompted for URL and tenant when using the official Checkmarx repository

This is the expected first-use flow

Enter the organization's Checkmarx One URL and tenant. They are remembered for subsequent use.

Developer is prompted for URL and tenant when using a preconfigured internal repository

Onboarding file is empty, invalid, or only one key is set

Check both keys in your fork (config/cx-onboarding.properties), not the live install

Wrong tenant or region at login

Stale ref or wrong values in the fork

Update the fork, bump the ref, and redeploy

Extension update removes the pre-fill

Rollout points at upstream instead of your fork

Point install commands/images at your internal repository and pinned ref

Hooks not loading after an update

Session cache

Run /extensions reload or restart Gemini CLI

System settings not taking effect

Wrong path for the OS, or GEMINI_CLI_SYSTEM_SETTINGS_PATH set to something else in the user's environment

Verify the path table in Deployment Methods; check for a stray environment variable override

Windows file lock during update/uninstall

A background process or IDE is holding the extension directory open

Close it and retry