How do I configure the AI provider with the CLI only?

[jpambrun]

I am trying to use but commit --ai, but I am getting

Generating commit message...
Error: Failed to initialize default OpenAI LLM provider

The only documentation is see is about the UI
https://docs.gitbutler.com/features/branch-management/ai-assistance#global-settings-global-settings--ai-options

I am running in headless WSL, how can I set this up? I can't seem to find any relevant documentaion.

[Byron]

Thanks a lot for asking!

I can definitely reproduce the issue. The error message doesn't help in sorting out the problem which is unfortunate.

gitbutler/crates/but/src/command/legacy/ai.rs

Lines 44 to 45 in 21c343b

	let llm = LLMProvider::default_openai()
	.ok_or_else(|| anyhow::anyhow!("Failed to initialize default OpenAI LLM provider"))?;

The underlying system doesn't provide any reasons for the failure either, hence the generic message.
This seems like a gap mostly in implementation (as a configuration command for AI is missing), and then documentation. Maybe the latter isn't important once the error message suggests how to fix the issue.

CC @krlvi and @estib-vega who have been working on this.

Auto-research

I did some digging through the public docs and the current source, and I don’t see a published doc page that answers this fully for CLI-only/headless use.

What I found:

• The existing AI docs are UI-oriented:
  • AI Assistance: https://docs.gitbutler.com/features/branch-management/ai-assistance
• The CLI docs mention but commit --ai, but they don’t explain how to configure AI credentials/providers from a headless environment:
  • but commit: https://docs.gitbutler.com/commands/but-commit
• but config also doesn’t appear to expose an ai subcommand or any documented CLI setup flow:
  • but config: https://docs.gitbutler.com/commands/but-config

From the source, but commit --ai appears to use the default OpenAI provider path:

• crates/but/src/command/legacy/ai.rs calls LLMProvider::default_openai()
• crates/but-llm/src/openai.rs shows that this falls back through:
  1. GitButler token
  2. stored OpenAI key
  3. OPENAI_API_KEY

That suggests the most likely current headless workaround is simply:

export OPENAI_API_KEY=...
but commit --ai

I also found code for broader AI provider config via Git config keys such as:

• gitbutler.aiModelProvider
• gitbutler.aiOpenAIKeyOption
• gitbutler.aiOpenAIModelName

but I did not find user-facing docs that explain how to set those from CLI only, and it’s not obvious that but commit --ai currently uses that path.

So unless I missed something, this looks like a documentation gap:

• but commit --ai is documented
• UI AI setup is documented
• headless/CLI-only AI setup is not documented clearly

If helpful, I can turn this into a docs issue or a proposed docs snippet.

[jpambrun]

Thanks for looking into it. I did some digging as well and looked at the implementation. I think the url should be configurable as well. I have a gitbutler config file in my home, but it appears undocumented.

Since we all have subscriptions, I was hoping it could look for claude or codex cli and use that if available.

[Byron]

Yes, I think this auto-configuration or discovery could be part of what these commands offer in future for improved UX.

[estib-vega]

Hey sorry about the inconvenience.

Just want to confirm what @Byron just said. It's not yet possible to configure AI through the CLI. One can manually configure the git config properties mentioned in the Auto-research part.

That said, the ability to configure the AI provider is coming to the CLI soon.

[estib-vega]

Since we all have subscriptions, I was hoping it could look for claude or codex cli and use that if available.

I don't know how that would work exactly. Knowing that there are some CLIs available would only help in that but would know to look for OpenAI or Anthropic API keys somewhere, so that they could be used in the headers of the API calls.

The problem I'd have with that approach would be that it feels wrong to have a third-party CLI looking for API keys to use.

[jpambrun]

I wasn't proposing that but hijack keys used by codex or claude. I was proposing that but could invoke codex/claude CLIs in non-interactive mode to generate the commit message from the diff.

[estib-vega]

I see. I wasn't aware of the non-interactive mode. Would be interesting to look into that