Skip to content
Back to search

masume

Terminal database client with AI chat and an MCP server

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/masumedb--masume/badge.svg)](/listings/masumedb--masume)

HTML

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

Install

i

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.

**mise**

mise use -g github:masumedb/masume@latest

Update: `mise upgrade github:masumedb/masume`

**npm** (`npx masume` runs without installing)

npm install -g masume

Update: `npm update -g masume`

**Go** (Go 1.27 or later)

go install github.com/masumedb/masume@latest

Update: run the same command again.

**Homebrew**

brew install masumedb/tap/masume

Update: `brew upgrade masumedb/tap/masume`

**Scoop**

scoop bucket add masumedb https://github.com/masumedb/scoop-bucket
scoop install masumedb/masume

Update: `scoop update` then `scoop update masume`

**Script** (installs to `~/.local/bin`)

curl -fsSL https://raw.githubusercontent.com/masumedb/masume/master/install.sh | sh

Update: run the script again. masume does not update itself.

**Debian and Ubuntu**

sudo dpkg -i masume_<version>_linux_<arch>.deb

Update: install the newer package with the same command.

**Fedora and RHEL**

sudo rpm -i masume_<version>_linux_<arch>.rpm

Update: `sudo rpm -U masume_<version>_linux_<arch>.rpm`

**Alpine** (the packages are unsigned)

sudo apk add --allow-untrusted masume_<version>_linux_<arch>.apk

Update: install the newer package with the same command.

**From source**

git clone https://github.com/masumedb/masume.git
cd masume
mise install
mise run install

Update: `git pull`, then `mise run install`.

The packages and archives are on the [releases page](https://github.com/masumedb/masume/releases/latest). For an archive, unpack the `tar.gz`, or the `zip` on Windows, and put `masume` on the PATH.

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.

README.md · README · 279 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">升目 masume</h1>
  2. <h3 align="center">A keyboard-first terminal database client with AI chat and an MCP server</h3>
  3. <p align="center">
  4. <a href="https://github.com/masumedb/masume/actions/workflows/check.yml"><img src="https://github.com/masumedb/masume/actions/workflows/check.yml/badge.svg" alt="check"></a>
  5. <img src="https://img.shields.io/badge/go-1.27+-00ADD8.svg?logo=go&logoColor=white" alt="Go">
  6. <img src="https://img.shields.io/badge/license-Apache--2.0-green.svg" alt="License">
  7. </p>
  8. <p align="center">
  9. <img src="vhs/demo.gif" alt="masume" />
  10. </p>
  11. **Engines:** PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, SQLite, Cassandra, ScyllaDB, Redis, MongoDB, and hosted services such as Neon, Supabase, PlanetScale, Turso, Redshift, and Amazon DocumentDB. See the [full list](docs/engines.md#protocols).
  12. ## Install
  13. **mise**
  14. ```sh
  15. mise use -g github:masumedb/masume@latest
  16. ```
  17. Update: `mise upgrade github:masumedb/masume`
  18. **npm** (`npx masume` runs without installing)
  19. ```sh
  20. npm install -g masume
  21. ```
  22. Update: `npm update -g masume`
  23. **Go** (Go 1.27 or later)
  24. ```sh
  25. go install github.com/masumedb/masume@latest
  26. ```
  27. Update: run the same command again.
  28. **Homebrew**
  29. ```sh
  30. brew install masumedb/tap/masume
  31. ```
  32. Update: `brew upgrade masumedb/tap/masume`
  33. **Scoop**
  34. ```powershell
  35. scoop bucket add masumedb https://github.com/masumedb/scoop-bucket
  36. scoop install masumedb/masume
  37. ```
  38. Update: `scoop update` then `scoop update masume`
  39. **Script** (Linux and macOS, installs to `~/.local/bin`)
  40. ```sh
  41. curl -fsSL https://raw.githubusercontent.com/masumedb/masume/master/install.sh | sh
  42. ```
  43. `MASUME_INSTALL_DIR` is the install directory, and `MASUME_VERSION` is the release tag, such as `v0.0.9`. The default is the latest release. The script checks the archive against `checksums.txt`.
  44. Update: run the script again. masume does not update itself.
  45. **Debian and Ubuntu**
  46. ```sh
  47. sudo dpkg -i masume_<version>_linux_<arch>.deb
  48. ```
  49. Update: install the newer package with the same command.
  50. **Fedora and RHEL**
  51. ```sh
  52. sudo rpm -i masume_<version>_linux_<arch>.rpm
  53. ```
  54. Update: `sudo rpm -U masume_<version>_linux_<arch>.rpm`
  55. **Alpine** (the packages are unsigned)
  56. ```sh
  57. sudo apk add --allow-untrusted masume_<version>_linux_<arch>.apk
  58. ```
  59. Update: install the newer package with the same command.
  60. **From source**
  61. ```sh
  62. git clone https://github.com/masumedb/masume.git
  63. cd masume
  64. mise install
  65. mise run install
  66. ```
  67. Update: `git pull`, then `mise run install`.
  68. The packages and archives are on the [releases page](https://github.com/masumedb/masume/releases/latest). For an archive, unpack the `tar.gz`, or the `zip` on Windows, and put `masume` on the PATH.
  69. Each release has a `checksums.txt` with the SHA-256 sum of every file, and a build provenance attestation for the archives, the packages and `checksums.txt`:
  70. ```sh
  71. sha256sum -c checksums.txt --ignore-missing
  72. gh attestation verify masume_<version>_linux_<arch>.tar.gz --repo masumedb/masume
  73. ```
  74. ## Quick start
  75. ```sh
  76. masume
  77. ```
  78. `masume` opens the connection picker. `n` adds a profile, and Enter connects. `Ctrl+N` returns to the picker from a connection. `?` shows the keys, and `Ctrl+K` opens the command palette. When `$DATABASE_URL` is set, `masume` opens that connection instead.
  79. A connection can also come from the command line:
  80. - `masume postgres://ada@127.0.0.1:5432/shop` opens a URL.
  81. - `masume ./notes.db` opens a SQLite file.
  82. - `masume --detect` lists the databases in running Docker or Podman containers and in the pods of the current `kubectl` context.
  83. The first interactive run creates a starter configuration file. A profile can also be written by hand:
  84. ```toml
  85. [profile.shop]
  86. engine = "postgres"
  87. host = "127.0.0.1"
  88. port = 5432
  89. database = "shop"
  90. user = "ada"
  91. auth = "prompt"
  92. env = "dev"
  93. mode = "write"
  94. ```
  95. `auth = "prompt"` prompts for the password at connection time. The password is kept only in memory unless it is saved to the keyring. See [configuration](docs/configuration.md) for every setting.
  96. ## Features
  97. ### Browse and query
  98. The explorer lists the database objects. Table views show data, columns, indexes, constraints, DDL, and query plans. An ER diagram shows a table and the tables linked to it by foreign keys.
  99. The editor has syntax highlighting and completion from the database catalog. Local checks, and server checks where the engine supports them, mark errors before execution. A statement with `:name` placeholders opens a form for the values. Query plans are drawn as a tree with estimated or measured costs.
  100. Query history and saved queries keep the statements. MongoDB takes a [subset of shell syntax](docs/engines.md#mongodb), Redis takes [commands, one per line](docs/engines.md#redis), and Cassandra takes [CQL with the keyspace as the schema](docs/engines.md#cassandra).
  101. ![The SQL editor with the completion menu open](vhs/shots/08-completion.png)
  102. ### Workspace
  103. - **Tabs:** query, table, notebook, and query builder tabs. The next connect restores them with their text, sort, and filters. See [tabs and history](docs/usage.md#tabs-and-history).
  104. - **Split view:** two tabs side by side or stacked, from one connection or from two. See [split view](docs/usage.md#split-view).
  105. - **Query builder:** tables, joins, filters, groups, and sorts drawn as a diagram, with the SQL under it. See [query builder](docs/usage.md#query-builder).
  106. - **Command palette:** every command by name, with its key. `Ctrl+K` opens it.
  107. - **Keys and mouse:** every key can be rebound. The mouse selects, scrolls, and drags the pane borders. See [keys](docs/keys.md) and [mouse controls](docs/usage.md#mouse-controls).
  108. - **Settings screen:** theme, icons, keys, AI, and MCP settings, written to the config file. See [settings](docs/usage.md#settings).
  109. ![A query and a table side by side in a split view](vhs/shots/21-split-view.png)
  110. ### Results and editing
  111. - **Grid:** sort, filter on the server or on loaded rows, follow a foreign key, or freeze a column. See [sorting and filters](docs/usage.md#sorting-and-filters).
  112. - **Staged edits:** insert, edit, duplicate, and delete rows in supported tables, then review the SQL before it runs. See [editing rows](docs/usage.md#editing-rows).
  113. - **Write plans:** row counts and reverse SQL for supported writes. See [write plans](docs/configuration.md#write-plans).
  114. - **Transactions:** begin, commit, and rollback. With autocommit off, running a statement starts a transaction.
  115. - **Masking:** hides columns with sensitive names in the grid only. Copies, exports, and value viewers show the original values.
  116. - **Copy and export:** CSV and JSON files. Clipboard formats also include Markdown, `INSERT` statements, row JSON, and column `IN` clauses. See [copy and export](docs/usage.md#copy-and-export).
  117. - **Import:** CSV or JSON into an existing or new SQL table, and JSON documents into a MongoDB collection. See [importing files](docs/usage.md#importing-files).
  118. - **Dump and restore:** schema and data as a SQL file. See [dump and restore](docs/usage.md#dump-and-restore).
  119. - **Data search:** a text in every column of every table of a schema. See [data search](docs/usage.md#data-search).
  120. - **Result compare:** pin a result and compare another one with it, row by row. See [result compare](docs/usage.md#result-compare).
  121. - **Schema compare:** tables, columns, indexes, and constraints of two schemas, on one connection or two. See [schema compare](docs/usage.md#schema-compare).
  122. - **Server dashboard:** sessions and metrics the engine supports. See [server activity](docs/usage.md#server-activity).
  123. ![A result grid](vhs/shots/09-result.png)
  124. ### Notebooks
  125. A notebook contains cells of prose, values, statements, and charts on one connection. Each cell keeps its result and its view. A notebook is a Markdown file, and `masume nb run` runs it. See [notebooks](docs/notebooks.md).
  126. ![A notebook of prose, values, statements, and a chart](vhs/shots/13-notebook.png)
  127. ### AI chat and MCP server
  128. The AI chat uses the current connection and asks for confirmation before each query, including reads. It works with Anthropic, OpenAI, Grok, and OpenAI-compatible providers, or a coding agent such as Claude Code. `[ai] enabled = false` hides the chat. See [AI chat](docs/ai.md).
  129. `masume --mcp` serves the allowed profiles to an external agent over stdio. It opens its own connections, with an access level per profile and one for the whole server. See [MCP server](docs/mcp.md).
  130. Both use the same database tools with different policies. See [security limits](SECURITY.md).
  131. ![The AI chat with the tool calls, the query, and the answer](vhs/shots/20-ai-chat.png)
  132. ### Connections and teams
  133. - **Password sources:** prompt, keyring, environment variables, commands, and named secret stores. Profile files do not store database passwords. See [credentials](SECURITY.md#credentials).
  134. - **Read-only profiles:** checked in the client, and also enforced by the server on engines that support it. See [read-only access](docs/engines.md#read-only-access).
  135. - **SSH tunnels and unix sockets:** see [SSH tunnel](docs/configuration.md#ssh-tunnel) and [unix socket](docs/configuration.md#unix-socket).
  136. - **Container detection:** `masume --detect` finds databases in running Docker or Podman containers, and in Kubernetes pods through `kubectl port-forward`. See [databases in a container](docs/usage.md#databases-in-a-container).
  137. - **Themes:** built-in themes, custom themes, or terminal colours. See [themes](docs/themes.md).
  138. A repository can share connections and saved queries in `.masume.toml`. masume reads the nearest one in or above the working directory:
  139. ```toml
  140. [profile.dev]
  141. engine = "postgres"
  142. host = "127.0.0.1"
  143. database = "shop"
  144. user = "shop"
  145. env = "dev"
  146. [query.recent-orders]
  147. sql = "select * from orders order by created_at desc limit 50"
  148. description = "the newest 50 orders"
  149. ```
  150. See [project file](docs/configuration.md#project-file) and [project security](SECURITY.md#project-files).
  151. ### Headless mode
  152. ```sh
  153. masume run -p shop-prod -f json 'select count(*) from orders'
  154. masume run -p shop -e ./reports/daily.sql --param day=2026-09-02
  155. masume run ./notes.db -f csv 'select * from notes limit 100000' > notes.csv
  156. masume run -p shop -f parquet 'select * from orders' > orders.parquet
  157. ```
  158. See [headless mode](docs/headless.md) for formats, exit codes, dump, restore, schema compare, and notebooks.
  159. ## Command line
  160. ```text
  161. masume open the client
  162. masume TARGET open a connection, postgres://you@host/shop
  163. masume --profile NAME open a user or project profile
  164. masume --detect open the picker with detected container and pod databases
  165. masume run [TARGET | -p NAME] STATEMENT run statements
  166. masume nb run [TARGET | -p NAME] FILE run a notebook
  167. masume dump [TARGET | -p NAME] FILE dump schema and data
  168. masume restore [TARGET | -p NAME] FILE restore a dump
  169. masume diff SOURCE TARGET compare the schemas of two connections
  170. masume FILE.masume.md open a notebook file
  171. masume --mcp serve allowed profiles over JSON-RPC on stdio
  172. masume --mcp --profile NAME serve one allowed profile
  173. masume --mcp --check check enabled MCP profiles
  174. masume --version, -v print the version
  175. masume --help, -h print the help
  176. ```
  177. Each command takes `--help`. A URL query key without a profile key of its own is passed to the driver. See [connection targets](docs/usage.md#connection-targets), [driver options](docs/configuration.md#driver-options), and [headless mode](docs/headless.md).
  178. ## Docs
  179. | Page | About |
  180. | --- | --- |
  181. | [User guide](docs/usage.md) | Workflows, navigation, editing, data transfer, and troubleshooting |
  182. | [Notebooks](docs/notebooks.md) | Cells, charts, run policy, and the file format |
  183. | [Configuration](docs/configuration.md) | Settings, defaults, profiles, and password sources |
  184. | [Engines](docs/engines.md) | Protocols, capabilities, ports, and data tools |
  185. | [Keys](docs/keys.md) | Default bindings, scopes, and overrides |
  186. | [Themes](docs/themes.md) | Built-in and custom themes |
  187. | [AI chat](docs/ai.md) | Providers, tools, and data sent to the provider |
  188. | [MCP server](docs/mcp.md) | Tools, limits, and write confirmation |
  189. | [Headless mode](docs/headless.md) | `masume run`, `nb run`, `dump`, `restore`, and `diff` for scripts and CI |
  190. | [Security](SECURITY.md) | Storage, data sharing, and protection limits |
  191. ## Contributing
  192. See [CONTRIBUTING.md](CONTRIBUTING.md).
  193. ## License
  194. Apache License 2.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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