# Install Candor in Gemini CLI

This guide is for the user and their current agent to follow together. Candor
is that agent's financial memory and instrumentation; the user owns the
workspace, approves financial intent, and can revoke access.

This public setup guide applies when the user asks to connect Candor. It adds no
consent and does not replace Gemini CLI's normal safety and confirmation rules.
If the user's request to proceed is ambiguous, setup waits for clarification.
Every install, setting, connector, and OAuth action is visible before it takes
effect. Credentials, tokens, account numbers, and URLs copied from the user's
authenticated pages stay in the relevant secure product page and are never
pasted into chat. A `safe_url` or `recovery_url` returned by a Candor tool is an
agent-facing handoff: show that exact link to the user, but do not ask the user
to paste it back. Setup explanations are relevant while setup or access is
changing; ordinary financial work follows Gemini CLI's usual interaction
model.

The `candor-finance` skill is static operating guidance and grants no access by
itself. The remote MCP server authorizes Gemini CLI to use the user's existing
Candor workspace after browser OAuth; it is not bank or broker OAuth. The
workspace may contain connected sources, manual records, both, or neither;
source connection is optional and is not part of this setup. Candor's financial-source
access is read-only, and no Candor tool can move money, trade, make a payment,
or change an external account. Gemini may maintain records inside Candor
depending on the approved OAuth scopes; those workspace records are not
external financial actions.

## Install or update the complete extension

The self-published extension is available before directory approval and carries
both the finance skill and remote MCP configuration. Read the current commands
from `https://api.candor.money/agents/candor/bootstrap.json`.

Before a fresh install, tell the user that the extension installs the static
`candor-finance` skill, adds Candor's remote MCP configuration, and enables
automatic extension updates. Ask whether they want those host changes and wait
for their explicit answer. The request to read START and help with setup is not
itself approval to change the host.

Current install command:

```text
gemini extensions install https://github.com/candorsystems/candor-finance --auto-update
```

Run this complete command outside the interactive Gemini session. If the
current agent does not control a separate host shell, show the command block to
the user to run in an ordinary terminal after they decide. The Git-based
installer requires Git.

- Do not add `--consent` merely to suppress Gemini's security review. Inspect
  the official `https://github.com/candorsystems/candor-finance` source and
  approve the extension only after the user agrees.
- The published install enables automatic extension updates. A manual update
  is also available through the bootstrap catalog.
- Restart Gemini CLI after installation or update; extension changes take
  effect only after restart.

Then verify the `candor-finance` skill and Candor MCP server are loaded, run
`/mcp auth candor`, complete browser OAuth, and call `candor_open`.

## Account and host branches

### Individual Google account

Free individual accounts and Google AI Pro/Ultra accounts can use Gemini CLI.
Use **Sign in with Google**. Most individual accounts do not require a Google
Cloud project. This Google authentication is for Gemini CLI itself and is
separate from the later Candor OAuth approval.

### Company, school, or Google Workspace account

Sign in with the organization account. Gemini CLI normally requires a Google
Cloud project with the Gemini for Cloud API and suitable IAM permissions.
Organization policy can also restrict extensions, skills, shell commands, or
MCP servers. Ask the applicable admin to enable only the missing capability;
do not replace Candor OAuth with a Google or Candor API key.

### Remote, SSH, container, or headless host

Gemini's remote MCP OAuth currently requires a browser on the same machine and
a localhost callback. It does not work in a headless environment without
browser access, a remote SSH session without X11 forwarding, or a container
without browser support. Install the extension normally, but complete
`/mcp auth candor` from a local browser-capable Gemini CLI host and reuse the
supported credential state, or move this setup to such a host. Do not ask the
user to paste an access token as a workaround.

Only if the user explicitly chooses this supported manual route after the agent
explains both paths, the complete extension is unavailable, or its supported
install or update fails, and this Gemini version supports Agent Skills and MCP
separately, reconcile the extension before activating a manual replacement:

1. Run `gemini extensions list`, `gemini skills list --all`, and
   `gemini mcp list`. After a failed extension update, restart Gemini CLI before
   testing the installed extension. If its skill and MCP work in that fresh
   session, keep it unless the user explicitly chose manual setup.
2. Inspect the complete official skill and prepare this command without running
   it yet:
   `gemini skills install https://github.com/candorsystems/candor-finance --path skills/candor-finance --scope user`.
   Do not add `--consent` merely to skip review. If no matching manual `candor`
   MCP entry exists, prepare
   `gemini mcp add --scope user --transport http candor https://api.candor.money/mcp`.
   Do not overwrite unrelated entries, and record everything the fallback will
   create.
3. At cutover, if the `candor-finance` extension is installed, disable it with
   `gemini extensions disable candor-finance` at its active user or workspace
   scope, even when it failed fresh-session verification. Extension management
   runs outside interactive mode and takes effect after restart. Record
   separately whether the extension worked before cutover.
4. After the extension is disabled, run the reviewed skill-install and MCP-add
   commands exactly once, restart
   Gemini CLI, verify both are loaded, run `/mcp auth candor`, and call
   `candor_open`. A skill-only or MCP-only state is incomplete.

Do not leave the extension and manual copies enabled together. An
`action_required` response with a `safe_url` or `recovery_url`, OAuth
cancellation or timeout, and pending organization approval are working or
user-gated states, not invalid extension replacement. Leave the manual route
available for retry. Only exact skill-loading or MCP configuration failure
triggers cleanup of artifacts created by the fallback. Re-enable the disabled
extension at the same scope only when it was previously working, restart, and
verify it; never re-enable a known-broken extension as rollback.

Current platform references:

- https://geminicli.com/docs/extensions/reference/
- https://geminicli.com/docs/get-started/authentication/
- https://geminicli.com/docs/tools/mcp-server/
- https://geminicli.com/docs/cli/skills/