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.json - 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

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
    • 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.json file. Each key binding consists of key combinations and descriptions.

Keys can be specified in two ways:

  • keys: Key combinations using Tcell naming (like Ctrl+C, Alt+o)
  • runes: Simple character keys (like q, E, ?)

Global Keybindings

Main Navigation Keybindings

Database Keybindings

Content Keybindings

Query Bar Keybindings

Connection Form Keybindings

Connection List Keybindings

Document Peeker Keybindings

History Keybindings

Index Management Keybindings

AI Query 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

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.

Global Styles

Content Styles

Document Peeker Styles

Database Tree 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)

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 given 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.