# litecli: a SQLite command-line client with auto-completion and syntax highlighting

> litecli is a Python CLI for SQLite databases that adds completion and syntax highlighting on top of the sqlite3 shell. It installs from PyPI or Homebrew, ships an optional sqlean extension bundle, and keeps its settings in a config file created on first launch.

**dbcli/litecli** — CLI for SQLite Databases with auto-completion and syntax highlighting

- Repository: https://github.com/dbcli/litecli
- Website: https://litecli.com
- Stars: 3,308 · Forks: 97
- Language: Python
- License: BSD-3-Clause
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/dbcli-litecli

## What litecli adds to the sqlite3 shell

The stock sqlite3 binary does its job: it opens a file, runs statements and prints results. What it does not do is help you type. litecli is aimed at the person who keeps a terminal open next to an editor and drops into a database dozens of times a day, running ad hoc SELECTs, checking a schema, or fixing a row by hand. The README describes it plainly as "A command-line client for SQLite databases that has auto-completion and syntax highlighting." That is the whole pitch, and it is a narrow one.

The people who benefit are the ones who already know SQLite and are tired of retyping table and column names. The people who do not benefit are the ones who never open an interactive shell: if your SQLite access happens through an ORM or a driver inside an application, a nicer prompt changes nothing about your day.

## How the completion, highlighting and config actually work

The dependency list in pyproject.toml tells you most of the architecture. prompt-toolkit (>=3.0.3,<4.0.0) provides the interactive line editor, which is where completion and key bindings come from. pygments (>=1.6) does the syntax highlighting. sqlparse (>=0.4.4) parses the SQL you type, which is what allows completion to be aware of statement structure rather than just matching a flat word list. cli-helpers supplies the tabular output formatting.

Because completion depends on knowing the schema, litecli has to introspect the connected database. That is why the client is built around a live connection rather than a batch runner: the completion engine needs the tables and columns of the file you opened. The config file is handled by configobj and is created automatically at first launch, at ~/.config/litecli/config on Unix-like systems and at ~\AppData\Local\dbcli\litecli\config on Windows. The README points you at the file itself for a description of the available options, which is a deliberate choice: the documentation for individual settings lives in the generated config, not in the README.

Two optional extras sit on top of the core. The sqlean extra pulls in sqlean-py and sqlean-stubs, a bundle of SQLite extensions. The ai extra pulls in llm plus setuptools and pip, and the comment in pyproject.toml notes that setuptools is there because the llm commands need it to install models. Neither extra is required for the basic client.

## Installing litecli and opening a database

The README gives two installation routes. With pip, and possibly sudo on Linux:

```bash
pip install -U litecli[sqlean]
```

The [sqlean] suffix is the optional extension bundle; plain pip install -U litecli works if you do not want it. On macOS, Homebrew is offered as an alternative:

```bash
brew install litecli
```

Once installed, the entry point is the litecli command, registered in pyproject.toml as litecli = "litecli.main:cli". The README's usage example is a single positional argument, the database file:

```bash
litecli --help
```

That prints a usage block whose examples section reads "litecli sqlite_db_name". So the first real use is to point it at a file:

```bash
litecli sqlite_db_name
```

If the file does not exist, the behaviour is whatever SQLite itself does when a client opens a missing path, and the README does not spell that out. On first launch, expect a config file to appear at ~/.config/litecli/config (or the Windows path above); open it to see the documented options. From there you are in an interactive prompt, and the completion and highlighting apply as you type.

## The sqlean extra and what it does not promise

The sqlean extra is the most interesting piece of packaging here, and also the one the README explains least. It installs sqlean-py (>=3.47.0) and sqlean-stubs (>=0.0.3). The stubs package is a typing aid, which suggests the maintainers care about editor and type-checker integration for the extension module, not just runtime behaviour. What the README does not do is list which extensions become available, how they are loaded into a session, or whether they are enabled by default once installed. If you are choosing litecli specifically for extension support, that is the gap to close before you commit, by reading the linked documentation rather than the README.

The ai extra raises a similar question from the other direction. It installs llm, setuptools and pip, and the inline comment explains that setuptools and pip are needed so the llm commands can install models. That means enabling the extra gives the client the ability to pull model packages onto your machine. The README does not describe the commands or what data leaves your machine when they run. Treat it as a feature to evaluate on its own terms, not as a reason to pick the client.

## Where litecli is the wrong tool

litecli is an interactive client. That single fact rules it out for a large class of jobs. If you are running migrations in CI, seeding a fixture database, or piping a query into a script, you want the sqlite3 binary or a language driver, not a prompt-toolkit application. The dependency chain is the cost: prompt-toolkit, pygments, sqlparse, cli-helpers and configobj all have to be installed, and the project requires Python 3.10 or newer. On a minimal container image, that is a meaningful footprint for something whose main value is a better prompt.

There is also a maintenance consideration that has nothing to do with code quality. The last push to main was on 2026-06-18. The most recent release listed is v1.17.1 from 2026-01-31, with v1.17.0 before it in September 2025 and v1.16.0 in August 2025. The repository is not archived, so it is not abandoned, but the release cadence is measured in months. If your team has a policy about how quickly upstream fixes must land, check the CHANGELOG before adopting.

Finally, litecli is SQLite only. If you work across PostgreSQL, MySQL and SQLite in the same week, a single client that speaks all three may be worth more to you than better completion in one of them.

## How litecli differs from usql and the sqlite3 binary

The closest alternative in the same niche is usql, which takes the opposite approach: one client, many database engines. Where litecli is built specifically around SQLite and can therefore introspect a SQLite file deeply for completion, usql generalises across engines and accepts the compromises that come with it. The difference is not quality, it is scope. If SQLite is the only database you touch, the specialised client has more room to be good at that one thing. If SQLite is one of five engines in your stack, a universal client saves you from context switching.

The other alternative is the sqlite3 binary that ships with SQLite itself. It has no Python dependency, no config file, and it is already on the machine. What it lacks is exactly what litecli exists to provide. Choosing between them is a question of how much time you spend typing SQL by hand versus how much you spend running it from scripts.

## Licence and upgrade cost

litecli is released under BSD-3-Clause, and pyproject.toml declares license = { text = "BSD" }. That is a permissive licence, which in practice means you can bundle it into internal tooling without the copyleft obligations a GPL-style licence would impose. The README and pyproject.toml do not discuss attribution requirements in detail, so read the LICENSE file in the repository root if you plan to redistribute it. This is a description of what the files say, not legal advice.

Upgrade cost is low and mostly invisible. The version is dynamic and derived by setuptools-scm from git tags, so installing from a source checkout without tags can produce an odd version string. Upgrading through pip is a single command, and the config file lives outside the package at ~/.config/litecli/config, so it survives upgrades. That also means a config written against an older release is not migrated for you; if an option is renamed or removed, the README points you at the file itself as the reference, and you will need to compare it against a fresh install.

## Conclusion

Adopt litecli if you spend real time in an interactive SQLite shell and want completion, highlighting and readable tabular output without leaving the terminal. Skip it if your work is scripted: the sqlite3 binary is already present on most systems and adds no Python dependency, and litecli is an interactive client, not a replacement for a driver in application code. Before committing, check that your Python is 3.10 or newer, since pyproject.toml sets requires-python to >=3.10, and read the config file it writes at ~/.config/litecli/config (or ~\AppData\Local\dbcli\litecli\config on Windows) to see which options you actually want to change. The last push to main was on 2026-06-18, so the project is still receiving commits rather than sitting archived.

## FAQ

### How do I open a SQLite file?

In litecli you pass the database file as the single positional argument, as in the README's usage example litecli sqlite_db_name. The README does not describe what happens when the path does not exist.

### Where is the litecli config file stored?

A config file is created automatically at first launch, at ~/.config/litecli/config on Unix-like systems and at ~\AppData\Local\dbcli\litecli\config on Windows. The README says to see the file itself for a description of all available options.

### What Python version does litecli require?

pyproject.toml sets requires-python to >=3.10, so Python 3.10 or newer is needed. The typing configuration in the same file also targets Python 3.10.

### How do I install litecli?

The README gives two routes: pip install -U litecli[sqlean], with sudo possibly needed on Linux, or brew install litecli on macOS. The [sqlean] suffix is optional and pulls in the sqlean extension bundle.

## Sources

- [dbcli/litecli on GitHub](https://github.com/dbcli/litecli)
- [License: BSD-3-Clause](https://github.com/dbcli/litecli/blob/main/LICENSE)
- [Project website](https://litecli.com)
- [README](https://github.com/dbcli/litecli/blob/main/README.md)
- [Releases](https://github.com/dbcli/litecli/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dbcli-litecli