Interactive CLI Setup Wizard: UI Design and Flow

This document outlines the user interface, prompts, and step-by-step flow for the interactive CLI setup wizard for the gemini-cli-proxy project.

Overall Wizard Flow
Step 1: Welcome & Initial Check
Step 2: Authentication & Credential Import
Step 3: AI Studio Integration
Step 4: Load Balancing
Step 5: Logging
Step 6: Local Development
Step 7: Review and Confirm
Step 8: Finalization
Edge Cases and Error Handling

Overall Wizard Flow

The following diagram illustrates the high-level flow of the setup wizard.

graph TD
    A[Start] --> B{Existing config.yaml?};
    B -- Yes --> B1[Confirm Overwrite];
    B1 -- No --> Z[Exit];
    B -- No --> C;
    B1 -- Yes --> C;
    C[Step 1: Welcome & Explanation] --> D[Step 2: Credential Import];
    D --> E{AI Studio Keys Found?};
    E -- Yes --> F[Step 3: Configure AI Studio];
    E -- No --> G;
    F --> G;
    G[Step 4: Configure Load Balancing] --> H[Step 5: Configure Logging];
    H --> I[Step 6: Configure Local Dev Server];
    I --> J[Step 7: Review Changes];
    J -- Confirm --> K[Write to config.yaml & wrangler.toml];
    J -- Cancel --> Z;
    K --> L[Step 8: Final Summary];
    L --> Z;

Step 1: Welcome & Initial Check

Goal

Welcome the user, explain the wizard's purpose, and check for an existing config.yaml file.

Mockups

Scenario 1: No config.yaml found

================================================================
  Welcome to the Gemini CLI Proxy Setup Wizard!
================================================================

This wizard will guide you through the initial setup of your project.
It will help you configure authentication, AI Studio integration,
and other settings by creating a 'config.yaml' and modifying
'wrangler.toml'.

Let's get started!

[Press Enter to continue]

Scenario 2: config.yaml found

================================================================
  Welcome to the Gemini CLI Proxy Setup Wizard!
================================================================

It looks like you already have a 'config.yaml' file.

This wizard will overwrite your existing configuration. We recommend
making a backup of your 'config.yaml' and 'wrangler.toml' files
before proceeding.

? Do you want to continue and overwrite your existing configuration? (Y/n)

Logic & Flow

Display the welcome banner.
Check for the existence of v:/gemini-cli-proxy/config.yaml.
If config.yaml does not exist:
- Display the standard welcome message.
- Wait for the user to press Enter.
If config.yaml exists:
- Display the warning message about overwriting the file.
- Prompt the user to confirm.
- If the user chooses "No" (or 'n'), exit the wizard with a message: Setup cancelled. Your files have not been changed.
- If the user chooses "Yes" (or 'y', or presses Enter), proceed to the next step.

Step 2: Authentication & Credential Import

Goal

Detect OAuth 2.0 credential files and, with user consent, import them into the project's local environment.

Mockups

Scenario 1: Credential Files Found

----------------------------------------------------------------
  Step 2: Authentication
----------------------------------------------------------------

I've found OAuth 2.0 credential files in the './oauth creds' directory.
These are needed to authenticate with Google's Gemini API.

For local development, these credentials need to be imported into a
'.dev.vars' file, which is used by Cloudflare Wrangler.

? Shall I import these credentials for you by running the 'npm run predev' script? (Y/n)

Follow-up 1a: User Consents

> Running 'npm run predev'...

[Output of the 'npm run predev' script will be displayed here]

✔ Credentials imported successfully.

[Press Enter to continue]

Follow-up 1b: User Declines

Skipping credential import. You can run 'npm run predev' manually later.

[Press Enter to continue]

Scenario 2: No Credential Files Found

----------------------------------------------------------------
  Step 2: Authentication
----------------------------------------------------------------

I couldn't find any OAuth 2.0 credential files in the './oauth creds' directory.

To use this proxy, you'll need to:
1. Follow the OAUTH_CREDENTIALS_GUIDE.md to generate your credentials.
2. Place the downloaded JSON files into the './oauth creds' directory.
3. Rerun this wizard or manually run 'npm run predev'.

[Press Enter to continue]

Logic & Flow

Check for the presence of .json files in the v:/gemini-cli-proxy/oauth creds/ directory.
If credential files are found:
- Display the explanation and prompt the user for consent to import.
- If the user agrees ("Yes"), execute the npm run predev command using child_process.
  - Stream the output of the command to the console.
  - On successful execution (exit code 0), display a success message.
  - On failure, display an error message and instructions to run it manually (see Edge Cases).
- If the user declines ("No"), display a message indicating that the step was skipped.
If no credential files are found:
- Display the instructional message explaining how to obtain and place the credential files.
Wait for the user to press Enter before proceeding.

Step 3: AI Studio Integration

Goal

Detect AI Studio API keys and allow the user to configure how they are used.

Mockups

Scenario 1: AI Studio Key File Found

----------------------------------------------------------------
  Step 3: AI Studio Integration
----------------------------------------------------------------

I've found an AI Studio key file ('ai_studio_keys.txt' or 'keys.txt').
You can use these keys as an alternative to the primary OAuth credentials,
which can improve reliability.

? Do you want to enable AI Studio integration? (Y/n)

Follow-up 1a: User Enables Integration

? How would you like to use your AI Studio keys? (Use arrow keys)
  > As a Backup (Recommended) - Use AI Studio keys only if the main credentials fail.
    Combine with Primary - Distribute requests between both credential types.

Follow-up 1b: User Declines Integration

AI Studio integration disabled. You can enable it later by editing 'config.yaml'.

[Press Enter to continue]

Scenario 2: No AI Studio Key File Found

----------------------------------------------------------------
  Step 3: AI Studio Integration
----------------------------------------------------------------

I didn't find an AI Studio key file ('ai_studio_keys.txt' or 'keys.txt')
in the './oauth creds' directory.

This feature allows you to use AI Studio keys as a fallback or in combination
with your main credentials. To enable it, add your keys to a file named
'ai_studio_keys.txt' in the './oauth creds' directory and rerun this wizard.

[Press Enter to continue]

Logic & Flow

Check for ai_studio_keys.txt or keys.txt in v:/gemini-cli-proxy/oauth creds/.
If a key file is found:
- Ask the user if they want to enable the feature.
- If "Yes":
  - Present the choice of strategies (fallback or combined).
  - The chosen value will be stored for writing to config.yaml (fallback_mode).
  - Default selection should be "As a Backup".
- If "No":
  - Set fallback_mode: disabled in the configuration.
  - Display a message confirming it's disabled.
If no key file is found:
- Display the informational message explaining the feature and how to enable it.
- Set fallback_mode: disabled in the configuration.
Wait for the user to press Enter before proceeding.

Step 4: Load Balancing

Goal

Allow the user to enable or disable load balancing across the available credentials.

Mockup

----------------------------------------------------------------
  Step 4: Load Balancing
----------------------------------------------------------------

Load balancing distributes requests across all your available credentials.
This can improve performance and reliability, especially under heavy use.

It is highly recommended to keep this enabled.

? Enable load balancing? (Y/n)

Logic & Flow

Display the explanation of the load balancing feature.
Prompt the user with a "Yes/No" question.
The default option will be "Yes".
The user's choice will determine the load_balancing.enabled boolean value in config.yaml.

Step 5: Logging

Goal

Allow the user to configure logging behavior.

Mockups

Initial Prompt

----------------------------------------------------------------
  Step 5: Logging
----------------------------------------------------------------

Enabling logging is useful for debugging and monitoring requests.
You can disable it if you don't need detailed output.

? Enable logging? (Y/n)

Follow-up: If Logging is Enabled

? Select the desired log level: (Use arrow keys)
  > info  - Basic information about requests and responses.
    debug - Detailed information for debugging.
    warn  - Warnings about potential issues.
    error - Only log errors.

Logic & Flow

First, ask the user if they want to enable logging (logging.enabled).
If "Yes":
- Set logging.enabled: true.
- Present a list of log levels (info, debug, warn, error).
- The user's selection will be stored as the value for logging.level in config.yaml.
- The default selection should be info.
If "No":
- Set logging.enabled: false.
- The log level question is skipped.

Step 6: Local Development

Goal

Configure the port for the local development server.

Mockup

----------------------------------------------------------------
  Step 6: Local Development Server
----------------------------------------------------------------

Please specify the port for the local development server. This will be
written to the 'dev' section of your 'wrangler.toml' file.

? Enter the local server port: (8787)

Logic & Flow

Prompt the user to enter a port number.
The default value will be 8787.
Input Validation:
- The input must be a valid integer between 1024 and 65535.
- If the input is invalid, display an error message (Invalid port. Please enter a number between 1024 and 65535.) and re-prompt the user.
The chosen port number will be used to update the dev.port value in wrangler.toml.

Step 7: Review and Confirm

Goal

Display a summary of all the configured settings and get final confirmation from the user before writing to the files.

Mockup

================================================================
  Configuration Summary
================================================================

The following settings will be written to 'config.yaml' and 'wrangler.toml'.

--- config.yaml ---
ai_studio:
  fallback_mode: fallback
load_balancing:
  enabled: true
logging:
  enabled: true
  level: info

--- wrangler.toml ---
[dev]
port = 8787

----------------------------------------------------------------

? Apply these changes? (Y/n)

Logic & Flow

Clear the screen for a clean summary view.
Display the "Configuration Summary" header.
Iterate through the in-memory configuration objects for config.yaml and wrangler.toml.
Print the settings that will be changed in a clean, readable format (e.g., YAML-like).
Prompt the user for final confirmation.
If the user confirms ("Yes"):
- Proceed to the file writing step.
If the user cancels ("No"):
- Exit the wizard with the message: Setup cancelled. No changes have been made.

Step 8: Finalization

Goal

Inform the user that the configuration has been successfully applied.

Mockup

Writing to 'config.yaml'...
Writing to 'wrangler.toml'...

✔ Configuration saved successfully!

================================================================
  Setup is complete!
================================================================

You can now start the local development server by running:

  npm run dev

Logic & Flow

After the user confirms in the previous step, write the in-memory configuration objects to their respective files (config.yaml and wrangler.toml).
Display progress messages for each file being written.
Show a final success message.
Provide the user with the next command to run (npm run dev).
Exit the wizard.

Edge Cases and Error Handling

This section details how the wizard should respond to unexpected situations, invalid inputs, and errors.

Step	Scenario	Error Message / Handling
1. Initial Check	User cancels at overwrite prompt.	`Setup cancelled. Your files have not been changed.` Then exit.
2. Credential Import	`npm run predev` script fails (non-zero exit code).	`[ERROR] Credential import failed. Please run 'npm run predev' manually and then restart the wizard.` Then exit.
2. Credential Import	`oauth creds` directory does not exist.	The check for `.json` files will simply fail, leading to the "No Credential Files Found" scenario, which is the correct behavior.
6. Local Development	User enters non-numeric port.	`Invalid port. Please enter a number between 1024 and 65535.` Re-prompt.
6. Local Development	User enters port outside the valid range (e.g., 80, 99999).	`Invalid port. Please enter a number between 1024 and 65535.` Re-prompt.
7. Review	User cancels at the final confirmation.	`Setup cancelled. No changes have been made.` Then exit.
General	User presses `Ctrl+C` at any point.	The wizard should exit gracefully. A message like `Setup aborted by user.` is recommended.
File I/O	Cannot write to `config.yaml` or `wrangler.toml` (e.g., permissions error).	`[ERROR] Could not write to [filename]. Please check file permissions and try again.` Then exit.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Interactive CLI Setup Wizard: UI Design and Flow

Table of Contents

Overall Wizard Flow

Step 1: Welcome & Initial Check

Goal

Mockups

Logic & Flow

Step 2: Authentication & Credential Import

Goal

Mockups

Logic & Flow

Step 3: AI Studio Integration

Goal

Mockups

Logic & Flow

Step 4: Load Balancing

Goal

Mockup

Logic & Flow

Step 5: Logging

Goal

Mockups

Logic & Flow

Step 6: Local Development

Goal

Mockup

Logic & Flow

Step 7: Review and Confirm

Goal

Mockup

Logic & Flow

Step 8: Finalization

Goal

Mockup

Logic & Flow

Edge Cases and Error Handling

FilesExpand file tree

CLI_WIZARD_DESIGN.md

Latest commit

History

CLI_WIZARD_DESIGN.md

File metadata and controls

Interactive CLI Setup Wizard: UI Design and Flow

Table of Contents

Overall Wizard Flow

Step 1: Welcome & Initial Check

Goal

Mockups

Logic & Flow

Step 2: Authentication & Credential Import

Goal

Mockups

Logic & Flow

Step 3: AI Studio Integration

Goal

Mockups

Logic & Flow

Step 4: Load Balancing

Goal

Mockup

Logic & Flow

Step 5: Logging

Goal

Mockups

Logic & Flow

Step 6: Local Development

Goal

Mockup

Logic & Flow

Step 7: Review and Confirm

Goal

Mockup

Logic & Flow

Step 8: Finalization

Goal

Mockup

Logic & Flow

Edge Cases and Error Handling