Start Gemini CLI in a clean working tree
If Claude Code is already part of your workflow, Gemini CLI should feel familiar: start inside a repository, explain a task, inspect proposed changes, and run checks. The useful differences are in authentication, project instructions, and tool permissions. Treat your first session as a controlled checkout, not a reason to redesign your workflow.
Before launching, run git status. Commit or stash unrelated changes so you can distinguish the agent’s edits from your own. Choose a small task with an obvious acceptance condition, such as adding a regression test for a reproducible bug.
Install the official CLI and check its commands
Use a Node.js version supported by the current Gemini CLI package. Check the package’s engine requirements rather than relying on an old setup article. Install with npm install -g @google/gemini-cli, then run gemini --version and gemini --help.
Record the installed version when documenting your setup. Authentication options, permission controls, and available models can change between releases. Inside an interactive session, use /help to discover the commands your installation actually supports instead of assuming Claude Code shortcuts transfer unchanged.
Choose one authentication route before troubleshooting
Gemini CLI supports different authentication paths, including Google sign-in and API-key-based access. Choose the route appropriate to your account and environment. An existing Claude Code credential does not automatically authenticate Gemini CLI, and a successful browser login does not prove that a relay API key is configured correctly.
For pay-as-you-go access across coding tools, SwiftRelay is a practical option: it supports Claude Code and Gemini CLI, with per-token billing. Sign up for SwiftRelay if you want to use that route; new accounts receive a small gift credit.
For a relay setup, follow its current Gemini CLI instructions. In a compatible CLI release, the relevant settings are GEMINI_API_KEY for the relay key and GOOGLE_GEMINI_BASE_URL for the endpoint override. SwiftRelay’s host is https://api.fastapirelay.com. Use the bare host for Gemini CLI; the /v1 suffix belongs to OpenAI-compatible SDK configurations.
Keep credentials in your shell environment or a secret manager, never in tracked project instructions. Select API-key authentication when prompted. If authentication fails, check the selected auth method, environment-variable visibility, endpoint, and model access separately. Avoid changing all four at once.
Translate CLAUDE.md into focused GEMINI.md guidance
Gemini CLI uses GEMINI.md for project instructions. Do not assume it automatically reads your existing CLAUDE.md. Start by transferring the repository facts that remain true regardless of the assistant:
- The package manager and exact test, lint, and build commands.
- Directory boundaries and generated files that should not be edited.
- Formatting conventions and expectations for regression tests.
- Actions requiring explicit approval, such as dependency changes or migrations.
Remove Claude-specific commands and permissions language rather than copying everything verbatim. Keep shared engineering rules aligned across both files. Ask Gemini to summarize the instructions it loaded before assigning a consequential task; this catches missing context early.
Run one bounded task with explicit tool boundaries
Start with a prompt such as: “Inspect the parser and its tests. Explain the failing edge case, propose a minimal fix, and wait before editing. Do not install dependencies or access external services.” This establishes a useful boundary, but prompt text is not a security control.
Review the CLI’s actual permission and sandbox settings. Avoid blanket approval during your first run. Read shell commands before accepting them, especially commands that delete files, modify credentials, install packages, or contact external systems.
Choose a model your account and endpoint actually expose. Gemini 2.5 Flash can be an option when available; use the provider’s supported model identifier rather than guessing it from a display name.
Finish the lap with tests and a diff
After approving the plan, request the smallest patch and the relevant checks. Then inspect git diff yourself. Confirm that tests were actually executed, distinguish failures from skipped checks, and look for unrelated edits.
Your first successful run should leave three reusable assets: a working authentication setup, a concise GEMINI.md, and a task prompt with clear acceptance criteria. Keep those stable before expanding permissions or handing over broader changes.