Setup and Diagnostics#
Commands for first-run setup, signing in to providers, scaffolding projects, and checking that your installation works.
gptme-onboard#
First-run onboarding wizard for gptme.
Helps you: - Detect available API providers - Select your preferred model - Create initial configuration - Test connectivity
Usage
gptme-onboard [OPTIONS]
Options
- --check#
Check setup status without making changes
- -v, --verbose#
Enable verbose output
gptme-auth#
Authenticate with various gptme providers.
Usage
gptme-auth [OPTIONS] COMMAND [ARGS]...
grok-subscription#
Authenticate with xAI using your SuperGrok subscription.
If you have the grok CLI installed and have run grok login, gptme
will automatically reuse those tokens — no extra steps needed.
If you don’t have the grok CLI, this command guides you through the same OAuth flow to obtain tokens stored at ~/.config/gptme/oauth/grok_subscription.json.
Usage
gptme-auth grok-subscription [OPTIONS]
login#
Login to gptme cloud using RFC 8628 Device Flow.
Initiates an OAuth Device Authorization Grant flow:
Works great for SSH sessions and headless environments.
Usage
gptme-auth login [OPTIONS]
Options
- --url <url>#
gptme service URL (used for LLM API and token storage).
- Default:
'https://kpkxgnfpyntahyhckhgm.supabase.co'
- --auth-url <auth_url>#
Override the device-auth endpoint base URL. Defaults to the Supabase edge function used by gptme.ai.
- --no-browser#
Don’t open the browser automatically.
logout#
Remove stored credentials for gptme cloud.
Usage
gptme-auth logout [OPTIONS]
Options
- --url <url>#
gptme service URL to log out from.
- Default:
'https://kpkxgnfpyntahyhckhgm.supabase.co'
openai-subscription#
Authenticate with OpenAI using your ChatGPT Plus/Pro subscription.
This opens a browser for you to log in with your OpenAI account. After successful login, tokens are stored locally for future use.
Usage
gptme-auth openai-subscription [OPTIONS]
openrouter#
Authenticate with OpenRouter via PKCE OAuth and store a permanent API key.
Opens a browser so you can sign in to openrouter.ai. After successful
sign-in, a permanent API key (sk-or-v1-…) is exchanged and saved to
the gptme config as env.OPENROUTER_API_KEY.
You can then use any model on OpenRouter:
gptme --model openrouter/anthropic/claude-sonnet-4-6 "Hello"
Usage
gptme-auth openrouter [OPTIONS]
status#
Show current login status for gptme cloud.
Usage
gptme-auth status [OPTIONS]
Options
- --url <url>#
gptme service URL to check.
- Default:
'https://kpkxgnfpyntahyhckhgm.supabase.co'
gptme-init#
Create a new gptme project scaffold.
Usage
gptme-init [OPTIONS] [PATH]
Options
- -i, --interactive#
Prompt for project details interactively.
- -t, --template <template_repo>#
Custom template repository (org/repo).
- -n, --name <name>#
Project name (default: directory basename).
- -d, --description <description>#
Short project description.
- --ci#
Include GitHub Actions CI workflow.
- --makefile#
Include a Makefile.
- --lessons#
Include lessons/ directory.
- --skills#
Include skills/ directory.
- --force#
Overwrite existing files.
Arguments
- PATH#
Optional argument
gptme-tutorial#
Interactive tutorial: learn gptme by doing.
Walks you through 3 hands-on tasks that teach gptme’s core capabilities: reading files, writing code, and fixing bugs. Each task runs gptme with a curated prompt, then checks whether the goal was achieved.
Run a specific task: gptme-tutorial –task 2
Usage
gptme-tutorial [OPTIONS]
Options
- --task <N>#
Run a specific task (1-3) instead of all.
gptme-doctor#
Run system diagnostics for gptme.
Checks API keys, tools, dependencies, configuration, and permissions to identify any issues that might affect gptme operation.
Usage
gptme-doctor [OPTIONS]
Options
- -v, --verbose#
Show detailed output
- --json#
Output as JSON