Skip to content
Back to search

harlequin

MarketplaceWorks with Claude CodeGitHub

The SQL IDE for Your Terminal. Now with hsql, your agent's favorite sql client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tconbeer/harlequin with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tconbeer/harlequin'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tconbeer--harlequin/badge.svg)](/listings/tconbeer--harlequin)

HTML

<a href="/listings/tconbeer--harlequin"><img src="/api/listings/tconbeer--harlequin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Harlequin is a Python program, and there are many ways to install and run it. We strongly recommend using [uv](https://docs.astral.sh/uv):

1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer). From a POSIX shell, run:

   curl -LsSf https://astral.sh/uv/install.sh | sh

Or using Windows Powershell:

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install Harlequin as a tool using `uv`:

   uv tool install harlequin

This command will install Harlequin into an isolated environment and add it to your PATH so you can easily run the executable.

Other Installation Methods

Alternatively, if you know what you're doing, after installing Python 3.9 or above, install Harlequin using `pip`, `pipx`, `poetry`, or any other program that can install Python packages from PyPI:

pip install harlequin

There is also a [Homebrew formula](https://formulae.brew.sh/formula/harlequin) for Harlequin, although this is maintained by the community and is not as rigorously tested as the Python installations. Note that the formula includes several Harlequin adapter packages (Postgres, MySQL/MariaDB, and ODBC) and their dependencies, which is convenient but increases the application size.

brew install harlequin

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "harlequin",
  3. "owner": {
  4. "name": "Ted Conbeer",
  5. "url": "https://github.com/tconbeer"
  6. },
  7. "metadata": {
  8. "description": "Plugins for Harlequin, the SQL IDE for your terminal, and hsql, your agent's favorite SQL client."
  9. },
  10. "plugins": [
  11. {
  12. "name": "hsql",
  13. "source": "./src/harlequin/hsql/skill"
  14. }
  15. ]
  16. }
README.md · README · 179 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Harlequin
  2. [![PyPI](https://img.shields.io/pypi/v/harlequin)](https://pypi.org/project/harlequin/)
  3. ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/harlequin)
  4. ![Runs on Linux | MacOS | Windows](https://img.shields.io/badge/runs%20on-Linux%20%7C%20MacOS%20%7C%20Windows-blue)
  5. The SQL IDE for Your Terminal.
  6. ![Harlequin](./harlequin.svg)
  7. > [!TIP]
  8. > This README contains a small subset of the docs available at
  9. > [harlequin.sh](https://harlequin.sh/docs/getting-started/index).
  10. ## Installing Harlequin
  11. Harlequin is a Python program, and there are many ways to install and run it. We strongly recommend using [uv](https://docs.astral.sh/uv):
  12. 1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer). From a POSIX shell, run:
  13. ```bash
  14. curl -LsSf https://astral.sh/uv/install.sh | sh
  15. ```
  16. Or using Windows Powershell:
  17. ```powershell
  18. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  19. ```
  20. 2. Install Harlequin as a tool using `uv`:
  21. ```bash
  22. uv tool install harlequin
  23. ```
  24. This command will install Harlequin into an isolated environment and add it to your PATH so you can easily run the executable.
  25. ### Other Installation Methods
  26. Alternatively, if you know what you're doing, after installing Python 3.9 or above, install Harlequin using `pip`, `pipx`, `poetry`, or any other program that can install Python packages from PyPI:
  27. ```bash
  28. pip install harlequin
  29. ```
  30. There is also a [Homebrew formula](https://formulae.brew.sh/formula/harlequin) for Harlequin, although this is maintained by the community and is not as rigorously tested as the Python installations. Note that the formula includes several Harlequin adapter packages (Postgres, MySQL/MariaDB, and ODBC) and their dependencies, which is convenient but increases the application size.
  31. ```bash
  32. brew install harlequin
  33. ```
  34. ## Installing Database Adapters
  35. Harlequin can connect to dozens of databases using adapter plug-ins. Adapters are distributed as their own Python packages that need to be installed into the same environment as Harlequin.
  36. For a list of known adapters provided either by the Harlequin maintainers or the broader community, see the [adapters](https://harlequin.sh/docs/adapters) page.
  37. The adapter docs also include installation instructions. Some adapters can be installed as Harlequin extras, like `postgres`. If you used `uv` to install Harlequin:
  38. ```bash
  39. uv tool install 'harlequin[postgres]'
  40. ```
  41. You can install multiple extras:
  42. ```bash
  43. uv tool install 'harlequin[postgres,mysql,s3]'
  44. ```
  45. ## Running Harlequin
  46. Once Harlequin is installed, you run it from the command line. The arguments and options you pass in at the command line affect Harlequin's behavior, like what database adapter it uses, which database it connects to, whether or not the file picker is visible, and more. Assuming you have installed Harlequin so that it is on your [PATH](<https://en.wikipedia.org/wiki/PATH_(variable)>) (`uv tool install harlequin` does this automatically), you run Harlequin by typing a command of this form into your shell:
  47. ```bash
  48. harlequin [OPTIONS] [CONN_STR]
  49. ```
  50. where `[OPTIONS]` is 0 or more pairs of the form `--[option-name] [option-value]`, and `[CONN_STR]` is 0 or more connection strings. `[OPTIONS]` are composed of both Harlequin options and adapter options. For a full list of options, run Harlequin with the `--help` option:
  51. ```bash
  52. harlequin --help
  53. ```
  54. ## Using Harlequin with DuckDB
  55. Harlequin defaults to using its DuckDB database adapter, which ships with Harlequin and includes the full DuckDB in-process database.
  56. To open an in-memory DuckDB session, run Harlequin with no arguments:
  57. ```bash
  58. harlequin
  59. ```
  60. To open one or more DuckDB database files, pass in relative or absolute paths as connection strings (Harlequin will create DuckDB databases if they do not exist):
  61. ```bash
  62. harlequin "path/to/duck.db" "another_duck.db"
  63. ```
  64. ## Using Harlequin with SQLite and Other Adapters
  65. Harlequin also ships with a SQLite3 adapter. To use that adapter, you specify the `--adapter sqlite` option. Like DuckDB, you can open an in-memory SQLite database by omitting the connection string:
  66. ```bash
  67. harlequin --adapter sqlite
  68. ```
  69. You can open one or more SQLite database files by passing in their paths as connection strings; note that the `--adapter` option has a short alias, `-a`:
  70. ```bash
  71. harlequin -a sqlite "path/to/sqlite.db" "another_sqlite.db"
  72. ```
  73. Other adapters can be installed as plug-ins; for more information, see the [installation guide](https://harlequin.sh/docs/getting-started/index#installing-database-adapters), and the guides for individual [adapters](https://harlequin.sh/docs/adapters). Each adapter can define its own options, which you can view using `harlequin --help`.
  74. ## Configuring Harlequin
  75. Harlequin contains a large number of options that allow you to [set the theme](https://harlequin.sh/docs/themes), [customize key bindings](https://harlequin.sh/docs/keymaps/index), [show remote and local files](https://harlequin.sh/docs/files/index), set the locale for number formatting, and much more. These can always be entered at the command line, but it can be convenient to define a configuration as a profile instead. For more information on configuring Harlequin, see [Using Config Files](https://harlequin.sh/docs/config-file/index).
  76. A profile's string values can name environment variables — `password = "${MYPASSWORD}"`, or `${MYHOST:-localhost}` to supply a default — so a config file your team shares holds no credentials, and values an adapter declares as secrets are masked wherever Harlequin prints them. hsql, Harlequin's companion CLI (below), reads the same files and can report on them, with `hsql --config show`, `--config validate` and `--config schema`.
  77. ## Using Harlequin with Agents or in Scripts
  78. Harlequin has a companion CLI, hsql, that uses the same adapters and config files, but is optimized for headless use by agents and in automations. hsql is packaged with Harlequin (no additional installation required):
  79. ```bash
  80. $ hsql -P dev -c "select * from users"
  81. id | name
  82. ----+---------
  83. 1 | Ted
  84. 2 | Patrick
  85. (2 rows)
  86. ```
  87. hsql can also explore the catalog without writing SQL: `hsql --catalog --path mydb.analytics` lists a schema's relations (and `--path mydb.analytics.orders` lists that table's columns), while `hsql --catalog-search customer_id` searches every level at once.
  88. To bound what an agent can do, `--read-only` connects in a mode the database refuses writes in, and `hsql --timeout 30` cancels a run that takes longer than that. Both are also profile keys, and both refuse to start if the adapter cannot enforce them. Harlequin takes `--read-only` too.
  89. For more information on hsql, see the [getting started docs](https://harlequin.sh/docs/getting-started/hsql).
  90. ## Using Harlequin with Django
  91. [django-harlequin](https://pypi.org/project/django-harlequin/) provides a command to launch Harlequin using Django’s database configuration, like:
  92. ```bash
  93. ./manage.py harlequin
  94. ```
  95. ## Keep Reading at [harlequin.sh](https://harlequin.sh/docs/getting-started/usage)
  96. Visit [harlequin.sh](https://harlequin.sh/docs/getting-started/usage) for an overview of features and full documentation, starting with a guided walkthrough of how to edit and execute queries, use the data catalog, export data, and more.
  97. ## Getting Help
  98. To view all command-line options for Harlequin and all installed adapters, after installation, simply type:
  99. ```bash
  100. harlequin --help
  101. ```
  102. To view a subset of these docs (and a link back here) from within the app, press `F1`.
  103. See the [Troubleshooting](https://harlequin.sh/docs/troubleshooting/index) guide for help with key bindings, appearance issues, copy-paste, etc.
  104. [GitHub Discussions](https://github.com/tconbeer/harlequin/discussions) are a good place to ask questions, request features, and say hello.
  105. [GitHub Issues](https://github.com/tconbeer/harlequin/issues) are the best place to report bugs.
  106. ## Sponsoring Harlequin
  107. Please consider [sponsoring Harlequin's author](https://github.com/sponsors/tconbeer), so he can continue to dedicate time to Harlequin.
  108. ## Contributing
  109. Thanks for your interest in Harlequin! Harlequin is primarily maintained by [Ted Conbeer](https://github.com/tconbeer), but he welcomes all contributions!
  110. Please see [`CONTRIBUTING.md`](./CONTRIBUTING.md) for more information.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.