GitHubGitHub

Vi Mongo Configuration Guide

Vi Mongo uses a flexible configuration system that allows you to customize various aspects of the application. This guide will walk you through the different configuration files and how to modify them.

Configuration Files

Vi Mongo uses three main configuration files:

  1. config.yaml - Main configuration file
  2. keybindings.yaml - Custom key mappings
  3. styles/*.yaml - Theme configuration files

All configuration files are stored in the vi-mongo configuration directory:

  • On Unix: ~/.config/vi-mongo/
  • On macOS: ~/Library/Application Support/vi-mongo/
  • On Windows: %APPDATA%\vi-mongo\

or the directory specified by the XDG_CONFIG_HOME environment variable.

Main Configuration

The main configuration file config.yaml contains the following sections:

General Settings

  • version: Configuration file version
  • showConnectionPage: Show connection page on startup (true/false)
  • showWelcomePage: Show welcome page on startup (true/false)
  • currentConnection: Name of the default MongoDB connection to use

Log Settings

  • path: Path to the log file
  • level: Log level (debug, info, warn, error)
  • prettyPrint: Format logs for better readability

Editor Settings

  • command: Custom command to use for editing documents
  • env: Environment variable to use for editor command (defaults to EDITOR)

Styles Settings

  • betterSymbols: Use improved symbols for UI elements (requires proper font support)
  • currentStyle: Currently active style file

MongoDB Connections

  • encryptionKeyPath: This is the path where encryption key can be stored (just plain key, nothing more). This key will be use to encrypt/decrypt all connections

Each connection has the following properties:

  • name: Unique name for the connection
  • url: MongoDB connection string (alternative to host/port)
  • host: MongoDB server hostname
  • port: MongoDB server port
  • database: Default database to connect to
  • username: MongoDB username
  • password: MongoDB password
  • timeout: Connection timeout in seconds
  • options (Optional):
    • authorizedDatabases: Only show databases the user is authorized to access (more here Mongodb List Databases)
    • authorizedCollections: Only show collections the user is authorized to access
    • alwaysConfirmActions: If set to false, actions such as deletion or duplication without confirmation are possible (defaults to Alt+d and Alt+D respectively).
    • limit: Default document limit per page - this will be set as default for all collections for given connection. To overtwrite this set diffrent limit in QueryOptions modal.

Keybindings Configuration

Vi Mongo supports extensive keyboard customization via the keybindings.yaml file. Each key binding consists of key combinations and descriptions.

Migration note: If you have an older keybindings.json file, Vi Mongo will automatically migrate it to keybindings.yaml on startup and back up the original as keybindings.json.bak.

IMPORTANT NOTE When configuring keybindings, Ctrl+<letter> is case-insensitive — Ctrl+L and Ctrl+l behave identically. For the Alt key, both uppercase and lowercase letters are handled correctly, so Alt+a and Alt+A are different keys.

Keys can be specified in two ways:

  • keys: Named or combo keys using Tcell naming (like Ctrl+c, Alt+o, Enter, Esc)
  • runes: Literal single characters, case-sensitive (like q, E, ?)

Example keybindings

Customizing Keybindings:

  • keys: An array of key combinations (e.g., [Ctrl+h, Enter])
  • runes: An array of single characters (e.g., [?, a])
  • description: A brief description of the action

Default Keybindings

To see all default keybindings go to Default Keybindings

Styling Configuration

Vi Mongo supports theme customization via style files stored in the styles/ directory. You can create and edit these files to customize the appearance of the application. Each theme can be changed using showStyleModal key which defaults to Ctrl+T

Example Styles

Style keys are divided into Color and Symbol. Colors use hexadecimal values, while symbols use ASCII or Unicode characters. Default icons shown above can be downloaded from Nerd Fonts

Default Styles

To see all default styles as yaml go to Default Styles

Other Notes

Environment Variables

Vi Mongo uses the following environment variables:

  1. EDITOR: Default editor to use for editing documents (can be overridden in config)
  2. ENV: When set to "vi-dev", development mode is enabled
  3. OPENAI_API_KEY: API key for OpenAI services (AI features)
  4. ANTHROPIC_API_KEY: API key for Anthropic services (Claude AI features)

Environment Variable URIs

Connection URLs in config.yaml can reference environment variables directly, making it safe to commit config files to version control:

The variable is expanded at connection time, so the actual URI is never stored on disk.

Known Keybinding Issues

When configuring keybindings, be aware of some potential issues:

  1. Ctrl+H: This key combination is often interpreted as the Backspace2 (Ctrl+backspace) key in terminal environments. For this case there is special handling in place to make it work as expected. For others like Ctrl+I there is no special handling in place, so those keybindings won't work as expected.
  2. Terminal Limitations: Some key combinations might not work as expected due to limitations in certain terminal emulators. If a keybinding doesn't seem to work, try an alternative combination.

If you encounter unexpected behavior with your custom keybindings, consider these potential issues and try alternative key combinations.

Applying Changes

After modifying any configuration file, you need to restart Vi Mongo for the changes to take effect. The application will automatically load the updated configuration on startup.

Resetting to Defaults

If you want to reset your configuration to the default settings, you can delete the configuration files from the ~/.config/vi-mongo directory. The next time you start Vi Mongo, it will recreate the configuration files with default values.

Troubleshooting

If you encounter any issues after modifying the configuration files, try the following steps:

  1. Verify that the YAML/JSON syntax is correct in the modified files.
  2. Check the application logs (default location: /tmp/vi-mongo.log) for any error messages.
  3. Reset to default configuration by deleting the configuration files and restarting the application.

If problems persist, please open an issue on the Vi Mongo GitHub repository with details about your configuration and the encountered problem.