codalotl Documentation

Installation

Install codalotl with Homebrew: brew install codalotl/tap/codalotl.

Alternatively, download the codalotl archive and extract the binary into your PATH (e.g., ~/bin if that's in your PATH, or /usr/local/bin).

Run it by typing codalotl in a terminal.

Configuring Keys

codalotl is BYOK (bring your own keys). You need API keys from an inference provider. All major providers are supported.

More details are provided below in Configuration. For now, the recommended way to set a key is with ENV variables. Set one of these to its respective API key:

OPENAI_API_KEY
XAI_API_KEY
ANTHROPIC_API_KEY
GEMINI_API_KEY

Your First Command

After you set a provider API key, run codalotl config, which prints your current configuration. You should see your (redacted) API key show up in the provider keys section (if it doesn't show up, you may need to run source on your shell profile file).

Now, cd to your Go project, then cd to a particular package you want to improve. Run codalotl doc ., which adds any missing documentation to the package.

Config file

Global configuration can be stored in ~/codalotl/codalotl.json. Project-specific configuration can be stored in codalotl.json or .codalotl.json in your project directory. Both global and project-specific configuration can exist - the project-specific configuration overwrites the global configuration on a per-property basis.

The config file is a strict JSON file. An example codalotl.json file:

{
  "providerkeys": {
    "anthropic": "sk-a...ABCD",
    "openai": "sk-a...EFGH",
    "xai": "xai-...MNOP",
    "gemini": "AIez...zyxW",
  },
  "logfile": "/Users/mrcody/codalotl/codalotl.log",
  "maxwidth": 180,
  "preferredprovider": "openai",
  "preferredmodel": "gpt-5"
}

Settings

• providerkeys: object with provider ID -> API key.
• logfile: absolute path to write logs to.
• maxwidth: column width for how wide comment blocks are. Generated documentation will be reflowed to this width.
• preferredprovider: provider ID to use by default (examples: openai, anthropic, xai, gemini).
• preferredmodel: model to use by default (see models with codalotl models).
• custommodels: array of objects, identifying custom models (this is how to use providers like openrouter).

Custom Models

You can use providers like openrouter, huggingface, deepseek, groq, and z.ai with custom models. The configuration file looks like this:

{
  "custom_models": [
      {
        "id": "or-gpt-5",
        "provider": "openrouter",
        "model": "openai/gpt-5",
        "apikeyenv": "",
        "apiendpointenv": "",
        "apiendpointurl": "",
        "reasoningeffort": "minimal"
      }
  ],
  "preferredmodel": "gpt-5"
}

• id: an ID that you define to let you refer to this model.
• provider: the provider ID.
• model: the provider's identifier for their model.
• apikeyenv (optional): look in this ENV var for the key (example: CUSTOM_PROVIDER_KEY).
• apiendpointurl (optional): Override the URL. Lets you effectively use any OpenAI-compatible API.
• reasoningeffort (optional): one of minimal, low, medium, high

Refer to your custom model's ID with the "preferredmodel" setting, or with the -model=my-custom-model command-line flag.

ENV Variables

In addition to setting your provider keys in the config file, you can set one of these ENV variables:

OPENAI_API_KEY
XAI_API_KEY
ANTHROPIC_API_KEY
GEMINI_API_KEY
OPENROUTER_API_KEY
HF_TOKEN
DEEPSEEK_API_KEY
GROQ_API_KEY
ZAI_API_KEY

Models

List available models with codalotl models. Configure which model you use with the "preferredmodel" setting, or run codalotl with the -model flag. Example: codalotl doc . -model=gpt-5

codalotl was primarily developed and tuned against OpenAI's latest model, currently gpt-5. In general, higher-intelligence thinking models produce better results with fewer false positives. Fast models like Claude Sonnet tend to produce worse results. For example, even for something simple like codalotl polish . (fix typos/grammar/spelling), lower intelligence models produce unnecessary churn because they're not smart enough to realize they're being pedantic nits - they reword documentation for no reason.

reflow

Reflow existing documentation to a specified maximum width. This is like gofmt but for documentation comments. It uses no AI and is fast.

codalotl reflow .

Notes

• Set "maxwidth" within your config.
• Other commands like polish also reflow. To see diffs more easily, reflow often and liberally.
• Sometimes reflowing will create a big paragraph where a list was intended. To fix, use actual Go comment lists (// - text)

doc

Generate documentation for Go source files that lack comments.

codalotl doc .

Optional flags

• -test: also document test files.
• -budget N: sets maximum input token budget (default: 10000).

polish

Fix spelling, grammar, and identifier typos in documentation. Applies documentation conventions and norms. Documentation semantically should remain the same.

codalotl polish .

Optional flags

• -ids=L: only polish these ids (comma separated). Ex: codalotl polish . -ids="myFunc,*myType.otherFunc".
• -file=S: only polish the specified file.

fix

Find and fix documentation errors.

codalotl fix .

Optional flags

• -ids=L: only fix these ids (comma separated). Ex: codalotl fix . -ids="myFunc,*myType.otherFunc".
• -file=S: only fix the specified file.

Notes

• Fixing documentation is a good way of finding bugs in your code. If the documentation says one thing but your code does another, fix will either literally tell you there's a bug, or produce a bizarre comment that tells you something is wrong.
• Only funcs and types are currently scanned for errors (they're the most important).

improve

Generate better docs for specific identifiers or a specific file. Relatively expensive, so specific ids or file is required. This works by generating new docs for an identifier, and then asking the LLM to pick the better docs.

codalotl improve . -file=S -ids=L

Flags

• -ids=L: only improve these ids (comma separated). Either -ids or -file is required.
• -file=S: only improve the specified file. Either -ids or -file is required.
• -hide-current (optional): hide current docs from the LLM before generating alternatives. Results are less anchored to current documentation.

reorg

Reorganize files and code in a package. First regroups code into (possibly new) files, then sorts the code within each file.

codalotl reorg .

Optional flags

• -file=S: only re-sort content within the specified file. Do not move it to new or other files.
• -one-pass: reorganizes the code with a single LLM call, using less intelligence, and often causing less change.
• You must have goimports or gopls installed - it fixes imports after content is moved around.

rename

Rename identifiers for consistency within a package. Embraces your naming conventions.

codalotl rename .

Notes

• Currently an experimental command. It shouldn't be wrong per se, but it's in an earlier stage of development than other refined commands.
• You must have gopls installed - it does the actual renames.

Support

Email support@codalotl.ai for support. Questions, feedback, bug reports, and feature requests are all appreciated!