Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- Google released Gemini API CLI in beta on October 27, 2026. The gemini-api command is for automation, while interactive Gemini CLI has its own workflow.
- Official versioned archives cover macOS, Linux, and Windows. Record which version and platform your CI job uses.
- Use --dry-run to validate a request offline. For a single JSON text result, use --stream=false -o json.
- Check output contracts and API costs separately. Media commands write files, and model and tool usage depends on the project and features you call.
Choose the tool for your script
The Gemini API CLI executable is gemini-api. It uses the Interactions API to generate text or media, analyze files, and run Gemini managed agents from automation that already has a shell. The CLI is stateless in the sense that commands have no hidden local session. To continue a conversation, explicitly save and pass the preceding interaction ID.
For interactive coding in a terminal, Google lists @google/gemini-cli separately. Consider the official SDKs when building a long-running application or service. If an existing shell script needs a model call, gemini-api can fit directly into that script.
Pin the version and configure the project key
Follow the official documentation's GitHub Releases link and choose a prebuilt macOS, Linux, or Windows archive for your OS and architecture. Put the binary on PATH. Pin the archive version in CI or containers and record the version and platform with the build. Check the flags and output in an isolated job before updating a beta version in a pipeline.
Inject GEMINI_API_KEY into the process that executes the command using your existing CI secret store. The API project governs permissions, quota, and billing. The official whoami command can help identify the active credential source. Record the source during diagnosis and keep the key out of logs.
Preview the request offline, then verify the call
Suppose your pipeline will process a small piece of non-sensitive test text. Preview it with gemini-api generate "Confirm CLI setup in one sentence." --dry-run. The docs say a dry run validates inputs locally and shows a redacted request. For a more complex payload, use gemini-api generate --schema to inspect the expected --body structure.
A dry run checks local parameters and request shape. For the first network test, use an approved project and a small input, then check the model, permissions, and response. Use --stream=false -o json for a single JSON result. Inspect the output format before plugging it into a parser so streaming chunks do not get read as a complete JSON document.
Handle file output, exit codes, and follow-up calls
Media commands generally write results to disk and can print a path on standard output. With -o json, read the metadata as documented and retrieve the file from the working directory. Track file paths separately from generated text so you can tell whether a model result, metadata, or local file is missing.
Exit code 2 indicates a usage or input validation issue, while 3 indicates an authentication or authorization issue. Code 1 covers network, quota, or runtime errors. Read the redacted error to distinguish them. Add --agent-mode for structured errors on standard error, and retain the returned ID from a background interaction so you can query it later.
Check costs for your project and model
Before integration, check the Gemini Developer API pricing tier for the model and features you plan to use. Some models or features have no free tier. For a paid project, confirm the chosen model, tools, and usage volume. A personal Gemini subscription or a successful CLI installation does not establish your API project's quota.
Use a controlled small input to compare expected and actual usage before increasing volume. For billing or access issues, record the project, model, time, and error type. These setup examples illustrate the workflow. Consult the actual API documentation for project-specific costs and availability.
Sources
Frequently Asked Questions
Does a successful dry run prove that my project has model access?
A dry run checks local request construction. Use a small, authorized live call to verify access, quota, and connectivity.
Will a text command continue a conversation without the previous ID?
Commands have no implicit session by default. To continue an interaction, pass the previous ID with --previous-interaction-id.