From e198d1b76895295fc54e62cb5dcc0e6803d1f8bd Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Sun, 8 Nov 2026 17:59:46 +0700 Subject: [PATCH 1/4] docs(integrations): document the rebuilt tablepro command line --- customization/general-settings.mdx | 2 +- developers/pairing.mdx | 26 +++- developers/tokens.mdx | 2 + developers/versioning.mdx | 13 +- docs.json | 1 + integrations/index.mdx | 9 +- integrations/mcp-clients.mdx | 2 +- integrations/terminal.mdx | 184 +++++++++++++++++++++-------- linux/command-line.mdx | 178 ++++++++++++++++++++++++++++ snippets/cli-exit-status.mdx | 7 ++ snippets/cli-output-formats.mdx | 10 ++ snippets/cli-schema-commands.mdx | 11 ++ snippets/stability-matrix.mdx | 6 +- 13 files changed, 385 insertions(+), 66 deletions(-) create mode 100644 linux/command-line.mdx create mode 100644 snippets/cli-exit-status.mdx create mode 100644 snippets/cli-output-formats.mdx create mode 100644 snippets/cli-schema-commands.mdx diff --git a/customization/general-settings.mdx b/customization/general-settings.mdx index c9201b3a..8d47a3a3 100644 --- a/customization/general-settings.mdx +++ b/customization/general-settings.mdx @@ -56,7 +56,7 @@ Older servers have neither: MySQL before 5.7.8, MariaDB before 10.1.1. A stateme ## Command line tool -Shows whether `/usr/local/bin/tablepro` links to this copy of the app, with the Terminal line that links or removes it. The command opens database URLs in the app. See [Terminal](/integrations/terminal). +Shows whether `/usr/local/bin/tablepro` links to this copy of the app, with the Terminal line that links or removes it. A copy running from the disk image or another read-only volume shows no line and asks to be moved to Applications first. The command opens database URLs and files in the app, and runs queries, browses schemas and exports tables from a shell. See [Terminal](/integrations/terminal). ## Trusted links diff --git a/developers/pairing.mdx b/developers/pairing.mdx index 7247e335..ffc5e415 100644 --- a/developers/pairing.mdx +++ b/developers/pairing.mdx @@ -100,7 +100,8 @@ Three constraints decide whether TablePro accepts the request at all: name, such as `smb://`, `ssh://` and `webcal://`. The exchange endpoint takes no bearer token: the single-use code plus the verifier is the credential. -It and `/mcp` are the only paths the server serves, and both accept `POST` only. +It, [the revoke route](#revoking-a-token) and `/mcp` are the only paths the server serves, and all +three accept `POST` only. ## Response modes @@ -162,9 +163,30 @@ takes a click. The sheet does not take focus from another app; TablePro's Dock i Approving mints the token, holds the plaintext against a one-time code for 5 minutes, and opens the redirect. Pairing again mints a second token rather than replacing the first, so an extension that -re-pairs should stop using its old one. Revoke either under +re-pairs should [revoke](#revoking-a-token) its old one, or the user revokes it under **Settings > MCP > Authentication**. +## Revoking a token + +A client done with its token, such as `tablepro unpair`, revokes it with an +[RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) request: a form body holding the token itself. + +```ts +await fetch(`http://127.0.0.1:${port}/v1/integrations/revoke`, { + method: "POST", + headers: { "Content-Type": "application/x-www-form-urlencoded" }, + body: new URLSearchParams({ token }), +}); +``` + +| Code | Meaning | +|------|---------| +| `200` | The token is revoked, or it was already revoked or never existed. Delete your copy either way. | +| `400 unsupported_token_type` | The token is the [stdio bridge token](/developers/tokens#the-stdio-bridge-token), which this route never revokes. | + +The route does what **Revoke** in **Settings > MCP > Authentication** does: the token's requests in +flight are cancelled and its next call gets `-33009`. See [Revocation](/developers/tokens#revocation). + ## Security properties | Property | How | diff --git a/developers/tokens.mdx b/developers/tokens.mdx index 37b907c2..2333ffe1 100644 --- a/developers/tokens.mdx +++ b/developers/tokens.mdx @@ -65,6 +65,8 @@ Revoking cancels every request that token has in flight and clears the connectio **Disconnect** in the Connected Clients list revokes that client's token. It is not a soft disconnect: the client has to pair again or be given a new token. +A client revokes its own token with `POST /v1/integrations/revoke`, as `tablepro unpair` does. See [Revoking a token](/developers/pairing#revoking-a-token). + ## The stdio bridge token Every server start mints a token named `__stdio_bridge__` and writes it into the [handshake file](/developers/mcp-protocol#local-socket-and-handshake) for the bundled bridge. The bridge sends it over the private socket after checking the socket and host process. It is **Read & Write**, so an agent going through the bridge can read and write but cannot call `confirm_destructive_operation`. diff --git a/developers/versioning.mdx b/developers/versioning.mdx index ce2efb2d..9f0a6c39 100644 --- a/developers/versioning.mdx +++ b/developers/versioning.mdx @@ -68,7 +68,7 @@ And within a major version, none of these happen: - A required input field is added to an existing tool. - An output field is removed or changes type. - A resource is removed. -- `/mcp` or `/v1/integrations/exchange` moves. +- `/mcp`, `/v1/integrations/exchange` or `/v1/integrations/revoke` moves. - A pairing parameter is removed, or the redirect changes how it delivers the code. - A scope is removed or renamed, or the exchange response drops `scope`. - The default port changes from `23508`. @@ -83,9 +83,10 @@ Treat the port as a setting that defaults to `23508`; the pane's **Status** row ### The tablepro command and the app's identity -- `tablepro`, once installed from **Settings > General**, stays at `/usr/local/bin/tablepro` and - hands each argument to the app the way `open -b com.TablePro` does: database URLs, `tablepro://` - links, `.sql` files and database files. With no argument it opens the app. +- `tablepro`, once installed from **Settings > General**, stays at `/usr/local/bin/tablepro`, and + its commands and options keep their names and meanings. +- Given database URLs, `tablepro://` links, `.sql` files or database files, `tablepro` opens them in + the copy of TablePro it ships in, or in the copy already running. With no argument it opens the app. - The bundle ID stays `com.TablePro`. - The MCP bridge stays at `Contents/MacOS/tablepro-mcp` inside the app bundle. - Where the bundle sits is up to the user. [Find the app](/developers#find-the-app) by bundle ID. @@ -108,8 +109,8 @@ Deprecated now: These can change in any release, without notice: -- Transport framing, internal message routing, and any HTTP path other than `/mcp` and - `/v1/integrations/exchange`. +- Transport framing, internal message routing, and any HTTP path other than `/mcp`, + `/v1/integrations/exchange` and `/v1/integrations/revoke`. - The [handshake file and private socket](/developers/mcp-protocol#local-socket-and-handshake). Use the bundled `tablepro-mcp` bridge, which finds the server on its own, or connect over HTTP to the port on the **Status** row in **Settings > MCP**, `23508` by default. diff --git a/docs.json b/docs.json index 1c755cd8..d45e244f 100644 --- a/docs.json +++ b/docs.json @@ -448,6 +448,7 @@ "linux/connect", "linux/sql-editor", "linux/data-grid", + "linux/command-line", "linux/keyboard-shortcuts", "linux/troubleshooting" ] diff --git a/integrations/index.mdx b/integrations/index.mdx index 8da46224..33a4ed3a 100644 --- a/integrations/index.mdx +++ b/integrations/index.mdx @@ -4,9 +4,10 @@ sidebarTitle: Overview description: Use TablePro from AI clients, Raycast, the terminal, DDEV and iOS Shortcuts --- -AI clients and the Raycast extension query your databases through the [MCP server](/features/mcp), -so its limits, tokens and activity log, all reached from **Settings > MCP**, apply to them. -The terminal, DDEV and iOS Shortcuts work without it. +AI clients, the Raycast extension and the `tablepro` command query your databases through the +[MCP server](/features/mcp), so its limits, tokens and activity log, all reached from +**Settings > MCP**, apply to them. Opening a link or a file from the terminal, DDEV and iOS Shortcuts +work without it. @@ -16,7 +17,7 @@ The terminal, DDEV and iOS Shortcuts work without it. Search connections, browse schemas and run SQL from Raycast. - Open database URLs and SQL files with the `tablepro` command. + Open database URLs and files, and query, browse and export a connection, with the `tablepro` command. Open a project's database with `ddev tablepro`. diff --git a/integrations/mcp-clients.mdx b/integrations/mcp-clients.mdx index 11ffe581..23cb0f0b 100644 --- a/integrations/mcp-clients.mdx +++ b/integrations/mcp-clients.mdx @@ -154,7 +154,7 @@ Zed, in `~/.config/zed/settings.json`: Claude Desktop starts MCP servers only as commands, so it needs a stdio-to-HTTP bridge of its own to reach this server. -The Linux server has nine tools: `list_connections`, `connect`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`, `browse_table`, `count_rows` and `execute_query`. Each connection's **External Clients** level decides what a client may do there: **Blocked**, **Read Only** (the default) or **Read & Write**. A write runs only after you click **Run** in the connection's window. **Regenerate Access Token…** turns the old token away at the next request, so paste the new one into every client. +The Linux server has eleven tools: `list_connections`, `connect`, `list_databases`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`, `browse_table`, `count_rows`, `execute_query` and `export_data`. The schema tools, `execute_query` and `export_data` take an optional `database`, which reaches only a database already open in the connection's window: its own, or one added with **Open Database…**. `execute_query` with `read_only: true` refuses any statement that is not a read. `export_data` returns tables as CSV, JSON or SQL `INSERT` statements, up to 1,000 rows each. Each connection's **External Clients** level decides what a client may do there: **Blocked**, **Read Only** (the default) or **Read & Write**. A write runs only after you click **Run** in the connection's window. **Regenerate Access Token…** turns the old token away at the next request, so paste the new one into every client. ## HTTP transport diff --git a/integrations/terminal.mdx b/integrations/terminal.mdx index d640ecd0..056e79d5 100644 --- a/integrations/terminal.mdx +++ b/integrations/terminal.mdx @@ -1,8 +1,12 @@ --- title: Terminal -description: Open database URLs and files in TablePro from a shell, and run queries from a script +description: Open database URLs and files in TablePro from a shell, and query, browse and export a connection from a script --- +import CliExitStatus from "/snippets/cli-exit-status.mdx"; +import CliOutputFormats from "/snippets/cli-output-formats.mdx"; +import CliSchemaCommands from "/snippets/cli-schema-commands.mdx"; + `open "mysql://…"` goes to whichever app claims the `mysql://` scheme, and with another database client installed that may not be TablePro. Name TablePro instead, either by bundle identifier or through the `tablepro` command: @@ -16,11 +20,16 @@ Any [connection URL](/connections/urls) works, including its query parameters. T connection when one matches on type, host, port, database and user; otherwise the session is temporary and never written to disk. Running `tablepro` with no argument opens the app and nothing else. + +TablePro for Linux ships the same command with the app. See [Command line](/linux/command-line). + + ## Add the tablepro command to your PATH -The command ships inside the app at `TablePro.app/Contents/SharedSupport/bin/tablepro`. It runs -`query` and `connections` itself and hands anything else to `open -b com.TablePro`. Link it into -`/usr/local/bin` once: +The command ships inside the app at `TablePro.app/Contents/SharedSupport/bin/tablepro` and works +with the copy it ships in: files and links open there, and a command that needs TablePro running +starts that copy. A copy already running from another folder receives them instead. Link the command +into `/usr/local/bin` once: ```bash sudo mkdir -p /usr/local/bin && sudo rm -f /usr/local/bin/tablepro && sudo ln -s /Applications/TablePro.app/Contents/SharedSupport/bin/tablepro /usr/local/bin/tablepro @@ -31,6 +40,10 @@ never asks for an administrator password. **Settings > General > Command Line** with the path of the copy you are running, and reads **Linked** once the link is in place. Any other directory on your `PATH` works too, and one you own needs no `sudo`. +A copy opened from the mounted disk image, or one macOS still runs from where it was downloaded (App +Translocation), sits on a read-only volume. Settings shows no line for it and asks you to move +TablePro to Applications. Move it, open it from there, and the line appears. + Command Line section in TablePro settings with the Terminal command to link tablepro Command Line section in TablePro settings with the Terminal command to link tablepro @@ -39,6 +52,9 @@ directory on your `PATH` works too, and one you own needs no `sudo`. To remove it, run `sudo rm /usr/local/bin/tablepro`. The link follows the app, so updating TablePro updates the command; move the app and the link needs making again. +`tablepro --version` prints the version of the app the command ships in. `tablepro --help` lists the +commands, and `tablepro help query` or `tablepro query --help` explains one. + ## Open a file Files route the same way, whether double-clicked in Finder or passed on the command line: @@ -55,6 +71,10 @@ tablepro app.db DuckDB plugin. A window already connected to that file comes to front instead of a second one opening. +`tablepro ` is short for `tablepro open `. A word that is neither an existing file nor a +URL opens nothing and exits 2, so `tablepro qeury` fails instead of starting the app. A file named +like a command, such as `tables`, opens with `./tables` or `tablepro open tables`. + ## Run a query ```bash @@ -64,8 +84,16 @@ echo "SELECT count(*) FROM orders" | tablepro query -c Staging --format json ``` `--connection` takes a saved connection's name or its id, and `tablepro connections` lists both. The -SQL comes from the argument, from `-f `, or from standard input. Rows go to standard output, -messages and errors to standard error. +SQL comes from the argument, from `-f `, or from standard input, and `-f -` reads standard +input even at a terminal, until `Ctrl+D`. Rows go to standard output, messages and errors to +standard error. + +SQL that starts with a dash, such as a leading `--` comment, goes after `--`, which ends the options: + +```bash +tablepro query -c Staging -- "-- weekly report +SELECT count(*) FROM orders" +``` | Option | | |---|---| @@ -75,76 +103,134 @@ messages and errors to standard error. | `--timeout` | Seconds the statement may run, 1 to 300. Defaults to **Query timeout** under **Settings > MCP**, 30 | | `--read-only` | Refuse any statement that is not a read, even on a connection set to **Read & Write** | -Pass `--format` in a script rather than relying on the terminal check. A result cut short by -`--limit` says so on standard error. +A result cut short by `--limit` says so on standard error. -| Exit status | Meaning | -|---|---| -| 0 | The statement ran | -| 1 | The database returned an error, or TablePro could not be reached | -| 2 | A usage error: a missing option, an unknown connection name, several statements in one run | -| 3 | Refused by a setting: the connection's level, Safe Mode, `--read-only`, a declined prompt, or a revoked pairing | -| 4 | The statement ran past its timeout | - -### Output formats - -| Format | NULL | Other values | -|---|---|---| -| `csv` | An empty field. An empty string is `""` | Quoted when they hold a comma, a quote or a line break | -| `tsv` | An empty field | Tab, line break, carriage return and backslash written as `\t`, `\n`, `\r`, `\\` | -| `json` | `null` | An array of objects keyed by column name | -| `jsonl` | `null` | One object per line | -| `table` | `NULL` | Columns padded to line up. A control character shows as an escape, such as `\n` or `\x1B` | +### What a query may do -Every value is text, as in the grid. Binary columns come out as Base64. Two columns with the same -name become `name` and `name_2` in JSON. +A query clears the same gates as any [MCP client](/features/mcp#connection-access), and so does +every other command that names a connection: + +- The connection's **External Clients** level: **Blocked** hides it, **Read Only** refuses writes. +- A connection whose AI policy is **Never** is hidden as well. A hidden connection reads as unknown, + by name or by id, and the command exits 2. +- The first query on each connection asks you, as often as **Approval** under **Settings > MCP** says. +- [Safe Mode](/features/safe-mode) confirms or authenticates writes on your Mac. +- `DROP` and `TRUNCATE` are refused. Run them in TablePro. +- One statement per run. A SQL Server script runs batch by batch at its `GO` lines and prints + every result set, separated by a blank line, or in JSON as one array per result set. + +Every statement goes to the execution audit log, and to the [history drawer](/features/query-history#sources) +under **Command Line**. + +## Browse a schema + +```bash +tablepro connections --format json +tablepro databases -c Staging +tablepro tables -c Staging --database app --schema public +tablepro describe -c Staging --schema public orders +tablepro describe -c Staging --ddl orders +``` + + + +## Export a table + +```bash +tablepro export -c Staging --format csv orders > orders.csv +tablepro export -c Staging --format sql --limit 5000 orders > orders.sql +``` + +`--format` is `csv`, `json` or `sql`, and `sql` writes `INSERT` statements in the connection's own +quoting. Each table stops at **Default row limit** under **Settings > MCP**, 500 unless you change +it, and `--limit` raises that as far as **Maximum row limit**. A table cut short says so on standard +error. For every row, use [Export](/features/import-export) in the app. + +A table name takes letters, digits and underscores, optionally as `schema.table`. For any other +name, run `tablepro query` with `--format csv` or `--format json`. -### Pair the command +## Pair the command The command reaches TablePro through its MCP server, so turn on **Enable MCP Server** under -**Settings > MCP** first. With it off, every run exits 3. When TablePro is not running, the command -starts it in the background, with no window. +**Settings > MCP** first. With it off, every command that reads from TablePro exits 3. When TablePro +is not running, the command starts its own copy in the background, with no window. - - TablePro asks **Allow tablepro command to access TablePro?** + + Any other command that reads from TablePro starts the same pairing the first time. TablePro asks + **Allow tablepro command to access TablePro?** The sheet starts at **Read Only**. Pick **Read & Write** if your scripts write, and limit the connections or set an expiry if you want. - Your browser opens a page saying the command is paired. Close it. The query you ran continues. + Your browser opens a page saying the command is paired. Close it. A command you ran continues. The token lives in your login Keychain. Revoke it under **Settings > MCP** and the next run exits 3; the run after that asks to pair again. A run whose standard error is not a terminal, such as a cron -job, exits 3 instead of opening the sheet. +job, exits 3 instead of opening the sheet. `tablepro pair` replaces the stored token with a new one; +run `tablepro unpair` first to revoke the old one. -### What a query may do +### Check or remove the pairing -A query clears the same gates as any [MCP client](/features/mcp#connection-access): +`tablepro status` shows the path and version of the copy the command belongs to, whether TablePro is +running, whether the MCP server is on, and whether the command is paired. It never starts TablePro +and never asks to pair. It exits 0 when a command can run now, 1 when TablePro is not running or +cannot be reached, and 3 when the server is off or the command is not paired. -- The connection's **External Clients** level: **Blocked** hides it, **Read Only** refuses writes. -- A connection whose AI policy is **Never** is refused. -- The first query on each connection asks you, as often as **Approval** under **Settings > MCP** says. -- [Safe Mode](/features/safe-mode) confirms or authenticates writes on your Mac. -- `DROP` and `TRUNCATE` are refused. Run them in TablePro. -- One statement per run. A SQL Server script runs batch by batch at its `GO` lines and prints - every result set, separated by a blank line, or in JSON as one array per result set. +`tablepro unpair` revokes the token in TablePro, then deletes it from the Keychain. When TablePro +cannot be reached, it deletes only the Keychain copy and says so. The token then stays active under +**Settings > MCP > Authentication** until you revoke it there. -Every statement goes to the execution audit log, and to the [history drawer](/features/query-history#sources) -under **Command Line**. +## Shell completion + +`tablepro completion zsh`, `bash` or `fish` prints a script that completes commands, options and +`--format` values. Connection names do not complete. Save the script where your shell loads it: -### List connections + + +```bash zsh +mkdir -p ~/.zsh/completion +tablepro completion zsh > ~/.zsh/completion/_tablepro +``` + +```bash bash +mkdir -p ~/.bash_completions +tablepro completion bash > ~/.bash_completions/tablepro.bash +echo 'source ~/.bash_completions/tablepro.bash' >> ~/.bash_profile +``` + +```bash fish +tablepro completion fish > ~/.config/fish/completions/tablepro.fish +``` + + + +zsh also needs the folder on its function path. Add these lines to `~/.zshrc` once, then open a new +shell: ```bash -tablepro connections --format json +fpath=(~/.zsh/completion $fpath) +autoload -U compinit && compinit ``` -Each entry has the connection's `name`, `id` and `type`, never a host, user or password. The list -leaves out connections the command may not reach. +Run the command again after an update that adds commands. + +## Exit status + + + +On the Mac, 3 also covers a command that is not paired and cannot ask, and a revoked pairing. + +## Output formats + + + +Every value is text, as in the grid. Binary columns come out as Base64. Two columns with the same +name become `name` and `name_2` in JSON. ## Trusting a link diff --git a/linux/command-line.mdx b/linux/command-line.mdx new file mode 100644 index 00000000..cd84e6b9 --- /dev/null +++ b/linux/command-line.mdx @@ -0,0 +1,178 @@ +--- +title: Command line +description: Run queries, browse schemas, export tables and open connection URLs from a terminal with TablePro for Linux +tag: "Beta" +--- + +import CliExitStatus from "/snippets/cli-exit-status.mdx"; +import CliOutputFormats from "/snippets/cli-output-formats.mdx"; +import CliSchemaCommands from "/snippets/cli-schema-commands.mdx"; + +The `tablepro` that starts the app is also its command line. A first word that names a command runs +in the terminal and prints there; a file, a URL or no argument at all opens the app. + + + +```bash .deb and .rpm +tablepro query -c Staging "SELECT id, email FROM users LIMIT 5" +``` + +```bash Flatpak +flatpak run app.tablepro.TablePro query -c Staging "SELECT id, email FROM users LIMIT 5" +``` + + + +The rest of this page writes `tablepro`. For Flatpak, put `flatpak run app.tablepro.TablePro` in its +place, or add `alias tablepro='flatpak run app.tablepro.TablePro'` to your shell's startup file. +`tablepro --help` lists the commands, `tablepro help query` explains one, and `tablepro --version` +prints the app's version. + +## Before the first command + +Commands go through the app's [MCP server](/integrations/mcp-clients#tablepro-for-linux), so two +things have to hold: + + + + The server runs only while the app is open, and a command never starts it. With the app closed, + a command exits 1 and says TablePro is not running. + + + Turn on **Preferences > MCP > Enable MCP Server**. With it off, a command exits 3. + + + +`tablepro status` checks both without starting anything. It exits 0 when a command can run now, 1 +when TablePro is not running, and 3 when the server is off. + +There is no pairing step. Each run reads the server's access token from the keyring where the app +keeps it, so **Regenerate Access Token…** needs nothing on the command line. A Flatpak command reads +the sandbox's own copy: run the command from the same installation as the app, since a native +`tablepro` cannot read a Flatpak app's token, nor the other way round. + +## Open files and connection URLs + +```bash +tablepro app.sqlite3 sales.duckdb +tablepro "postgresql://ada@db.example.com:5432/shop" +tablepro --new-window schema.sql +``` + +A database file opens as a session, as in [SQLite and DuckDB files](/linux/connect#sqlite-and-duckdb-files), +and a `.sql` file opens in an editor tab. `--new-window`, or `-n`, opens them in a new window. + +`tablepro ` is short for `tablepro open `. A word that is neither an existing file nor a +URL opens nothing and exits 2. A file named like a command, such as `tables`, opens with `./tables` +or `tablepro open tables`. + +### Connection URLs + +These schemes open in TablePro from a terminal, and from a link in a browser or any other app: + +| Engine | Schemes | +|---|---| +| PostgreSQL | `postgresql`, `postgres` | +| MySQL and MariaDB | `mysql`, `mariadb`, `mysqlx` | +| SQL Server | `sqlserver`, `mssql` | +| ClickHouse | `clickhouse`, `ch` | +| Cassandra and ScyllaDB | `cassandra`, `cql`, `scylla`, `scylladb` | +| Redis | `redis`, `rediss`, `valkey`, `valkeys` | +| MongoDB | `mongodb`, `mongodb+srv` | +| SQLite | `sqlite`, `sqlite3` | +| DuckDB | `duckdb` | + +A URL that matches a saved connection asks before opening it. `Enter` and `Escape` both cancel, so +click **Open** to go ahead. Any other URL opens the connect dialog filled from it: check the host, +user and database, then click **Connect**, which saves the connection once it connects. A password in +the URL goes to the **Password** row only, and is never logged or shown. + +## Run a query + +```bash +tablepro query -c Staging --format csv "SELECT id, email FROM users LIMIT 5" +tablepro query -c Staging -f report.sql > report.csv +echo "SELECT count(*) FROM orders" | tablepro query -c Staging --format json +``` + +`-c` takes a saved connection's name or id, and `tablepro connections` lists both. The SQL comes +from the argument, from `-f `, or from standard input, and `-f -` reads standard input even at +a terminal. Under Flatpak, `-f` reads files in your home folder, `/media`, `/run/media` and `/mnt`; +pass any other file on standard input. + +SQL that starts with a dash, such as a leading `--` comment, goes after `--`, which ends the options: + +```bash +tablepro query -c Staging -- "-- weekly report +SELECT count(*) FROM orders" +``` + +| Option | | +|---|---| +| `--database` | A database already open in the connection's window: its own, or one added with **Open Database…** on its sidebar row. Without it, the connection's own database | +| `--format` | `csv`, `tsv`, `json`, `jsonl` or `table`. `table` on a terminal, `csv` into a pipe or a file | +| `--limit` | Rows to return, 100 by default and 1,000 at most | +| `--timeout` | Seconds the statement may run, 1 to 300, 30 by default | +| `--read-only` | Refuse any statement that is not a read, even on a connection set to **Read & Write** | + +`query` has no `--schema`. Qualify table names in the SQL instead, as in `public.orders`. A result cut +short by `--limit` says so on standard error. + +### The connection has to be open + +A command that names a connection works on a session open in TablePro. Run from a terminal, it opens +a closed connection in a window, which may ask for the password, and waits up to 5 minutes for it to +connect. Run from a script or a cron job, where standard error is not a terminal, it exits 1 instead: +open the connection in TablePro first. + +### What a query may do + +- The connection's **External Clients** level: **Blocked** hides it, so the command exits 2 as for an + unknown name. **Read Only**, the default, refuses writes. +- On **Read & Write**, a write runs only after you click **Run** in the connection's window. +- The connection's Safe Mode applies, as in the editor. +- One statement per run, or one batch on SQL Server. + +## Browse a schema + +```bash +tablepro connections --format json +tablepro databases -c Staging +tablepro tables -c Staging --schema public +tablepro describe -c Staging --schema public orders +tablepro describe -c Staging --ddl orders +``` + + + +`--database` reaches only a database already open in the connection's window, as for `query`. + +## Export a table + +```bash +tablepro export -c Staging --format csv orders > orders.csv +tablepro export -c Staging --format sql orders > orders.sql +``` + +`--format` is `csv`, `json` or `sql`, and `sql` writes `INSERT` statements in the engine's own +quoting. Each table stops at 1,000 rows, and a table cut short says so on standard error. For every +row, open the table and use [Export Rows…](/linux/data-grid#copy-and-export) on every saved row. + +## Shell completion + +The .deb and .rpm packages install completions for bash, zsh and fish. Open a new shell after +installing, and `Tab` completes commands, options and `--format` values; zsh needs `compinit` in +`~/.zshrc`, as most setups have. Connection names do not complete. Flatpak installs no completions. + +`tablepro completion bash`, `zsh` or `fish` prints the same script. + +## Exit status + + + +On Linux, 1 also covers TablePro not running, and a closed connection when the command runs outside +a terminal. + +## Output formats + + diff --git a/snippets/cli-exit-status.mdx b/snippets/cli-exit-status.mdx new file mode 100644 index 00000000..c9e4762b --- /dev/null +++ b/snippets/cli-exit-status.mdx @@ -0,0 +1,7 @@ +| Exit status | Meaning | +|---|---| +| 0 | Done, `--help`, `--version` and `completion` included | +| 1 | The database returned an error, TablePro could not be reached, or the output could not be written | +| 2 | A usage error: an unknown command or option, a missing `--connection`, a connection name or id the command cannot see, several statements in one run, no SQL, or a target that is neither a URL nor a file | +| 3 | Refused by a setting: the MCP server is off, the connection's **External Clients** level, Safe Mode, `--read-only`, or a declined prompt | +| 4 | Timed out: the statement ran past its timeout, or a prompt in TablePro went unanswered | diff --git a/snippets/cli-output-formats.mdx b/snippets/cli-output-formats.mdx new file mode 100644 index 00000000..bd38806f --- /dev/null +++ b/snippets/cli-output-formats.mdx @@ -0,0 +1,10 @@ +| Format | NULL | Other values | +|---|---|---| +| `csv` | An empty field. An empty string is `""` | Quoted when they hold a comma, a quote or a line break | +| `tsv` | An empty field | Tab, line break, carriage return and backslash written as `\t`, `\n`, `\r`, `\\` | +| `json` | `null` | An array of objects keyed by column name | +| `jsonl` | `null` | One object per line | +| `table` | `NULL` | Columns padded to line up, wide characters included. A control character shows as an escape, such as `\n` or `\x1B` | + +`query` and every listing command take the same `--format`: `table` on a terminal, `csv` into a pipe +or a file. Pass it in a script rather than relying on the terminal check. diff --git a/snippets/cli-schema-commands.mdx b/snippets/cli-schema-commands.mdx new file mode 100644 index 00000000..7a0b0135 --- /dev/null +++ b/snippets/cli-schema-commands.mdx @@ -0,0 +1,11 @@ +| Command | Prints | +|---|---| +| `connections` | Each saved connection's `name`, `id` and `type`, never a host, user or password. Connections the command may not reach are left out | +| `databases` | The connection's databases | +| `schemas` | The schemas in a database | +| `tables` | The tables and views in a schema | +| `describe ` | The table's columns, indexes and foreign keys. With `--ddl`, its `CREATE` statement | + +Every command but `connections` takes `-c` with a saved connection's name or id. `schemas` takes +`--database`, and `tables`, `describe` and `export` take `--database` and `--schema`. Without them, +the connection's current database and schema apply. diff --git a/snippets/stability-matrix.mdx b/snippets/stability-matrix.mdx index a3fb1e90..e1e728b9 100644 --- a/snippets/stability-matrix.mdx +++ b/snippets/stability-matrix.mdx @@ -4,9 +4,9 @@ | `tablepro://` links on iPhone and iPad | `connect/` and `connect//table/` | New paths | | Database URLs | Every scheme and query parameter on [Connection URLs](/connections/urls) | New schemes and parameters | | AppleScript | Every term in the dictionary, with its four-character code | New classes, properties, commands, enumerators and optional parameters | -| MCP server | Tools, resources, prompts, error codes, `/mcp`, `/v1/integrations/exchange`, and the default port `23508` | New tools, resources, prompts, codes, optional inputs and output fields | -| Pairing | The `integrations/pair` link and its parameters, the code sent to `redirect`, and the exchange | New optional parameters | -| `tablepro` command | `/usr/local/bin/tablepro` and the arguments it takes | New kinds of argument | +| MCP server | Tools, resources, prompts, error codes, `/mcp`, `/v1/integrations/exchange`, `/v1/integrations/revoke`, and the default port `23508` | New tools, resources, prompts, codes, optional inputs and output fields | +| Pairing | The `integrations/pair` link and its parameters, the code sent to `redirect`, the exchange, and token revocation | New optional parameters | +| `tablepro` command on the Mac | `/usr/local/bin/tablepro`, its commands and their options | New commands and options | | App identity | Bundle ID `com.TablePro`, and `Contents/MacOS/tablepro-mcp` inside the bundle | Nothing | | Install location | Not covered | Anything. Find the app by bundle ID | | Files, preferences and Keychain items the app writes | Not covered | Anything. See [what is not under the contract](/developers/versioning#what-is-not-under-the-contract) | From 6ba1b1fc5ad9ac8fe2809ad1d81c94fcc13fde50 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Sun, 8 Nov 2026 22:44:28 +0700 Subject: [PATCH 2/4] docs(integrations): the revoke route serves the private socket only --- developers/pairing.mdx | 23 +++++------------------ developers/tokens.mdx | 2 +- developers/versioning.mdx | 6 +++--- snippets/stability-matrix.mdx | 4 ++-- 4 files changed, 11 insertions(+), 24 deletions(-) diff --git a/developers/pairing.mdx b/developers/pairing.mdx index ffc5e415..15dfeed1 100644 --- a/developers/pairing.mdx +++ b/developers/pairing.mdx @@ -168,24 +168,11 @@ re-pairs should [revoke](#revoking-a-token) its old one, or the user revokes it ## Revoking a token -A client done with its token, such as `tablepro unpair`, revokes it with an -[RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) request: a form body holding the token itself. - -```ts -await fetch(`http://127.0.0.1:${port}/v1/integrations/revoke`, { - method: "POST", - headers: { "Content-Type": "application/x-www-form-urlencoded" }, - body: new URLSearchParams({ token }), -}); -``` - -| Code | Meaning | -|------|---------| -| `200` | The token is revoked, or it was already revoked or never existed. Delete your copy either way. | -| `400 unsupported_token_type` | The token is the [stdio bridge token](/developers/tokens#the-stdio-bridge-token), which this route never revokes. | - -The route does what **Revoke** in **Settings > MCP > Authentication** does: the token's requests in -flight are cancelled and its next call gets `-33009`. See [Revocation](/developers/tokens#revocation). +`tablepro unpair` revokes its own token with an [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) +request to `/v1/integrations/revoke`. The route listens on the +[private socket](/developers/mcp-protocol#local-socket-and-handshake) only, which is not under the +[contract](/developers/versioning#what-is-not-under-the-contract). Revoke any other client's token in +**Settings > MCP > Authentication**. ## Security properties diff --git a/developers/tokens.mdx b/developers/tokens.mdx index 2333ffe1..8275e167 100644 --- a/developers/tokens.mdx +++ b/developers/tokens.mdx @@ -65,7 +65,7 @@ Revoking cancels every request that token has in flight and clears the connectio **Disconnect** in the Connected Clients list revokes that client's token. It is not a soft disconnect: the client has to pair again or be given a new token. -A client revokes its own token with `POST /v1/integrations/revoke`, as `tablepro unpair` does. See [Revoking a token](/developers/pairing#revoking-a-token). +`tablepro unpair` revokes its own token. See [Revoking a token](/developers/pairing#revoking-a-token). ## The stdio bridge token diff --git a/developers/versioning.mdx b/developers/versioning.mdx index 9f0a6c39..9f0babd5 100644 --- a/developers/versioning.mdx +++ b/developers/versioning.mdx @@ -68,7 +68,7 @@ And within a major version, none of these happen: - A required input field is added to an existing tool. - An output field is removed or changes type. - A resource is removed. -- `/mcp`, `/v1/integrations/exchange` or `/v1/integrations/revoke` moves. +- `/mcp` or `/v1/integrations/exchange` moves. - A pairing parameter is removed, or the redirect changes how it delivers the code. - A scope is removed or renamed, or the exchange response drops `scope`. - The default port changes from `23508`. @@ -109,8 +109,8 @@ Deprecated now: These can change in any release, without notice: -- Transport framing, internal message routing, and any HTTP path other than `/mcp`, - `/v1/integrations/exchange` and `/v1/integrations/revoke`. +- Transport framing, internal message routing, and any HTTP path other than `/mcp` and + `/v1/integrations/exchange`. - The [handshake file and private socket](/developers/mcp-protocol#local-socket-and-handshake). Use the bundled `tablepro-mcp` bridge, which finds the server on its own, or connect over HTTP to the port on the **Status** row in **Settings > MCP**, `23508` by default. diff --git a/snippets/stability-matrix.mdx b/snippets/stability-matrix.mdx index e1e728b9..96208602 100644 --- a/snippets/stability-matrix.mdx +++ b/snippets/stability-matrix.mdx @@ -4,8 +4,8 @@ | `tablepro://` links on iPhone and iPad | `connect/` and `connect//table/` | New paths | | Database URLs | Every scheme and query parameter on [Connection URLs](/connections/urls) | New schemes and parameters | | AppleScript | Every term in the dictionary, with its four-character code | New classes, properties, commands, enumerators and optional parameters | -| MCP server | Tools, resources, prompts, error codes, `/mcp`, `/v1/integrations/exchange`, `/v1/integrations/revoke`, and the default port `23508` | New tools, resources, prompts, codes, optional inputs and output fields | -| Pairing | The `integrations/pair` link and its parameters, the code sent to `redirect`, the exchange, and token revocation | New optional parameters | +| MCP server | Tools, resources, prompts, error codes, `/mcp`, `/v1/integrations/exchange`, and the default port `23508` | New tools, resources, prompts, codes, optional inputs and output fields | +| Pairing | The `integrations/pair` link and its parameters, the code sent to `redirect`, and the exchange | New optional parameters | | `tablepro` command on the Mac | `/usr/local/bin/tablepro`, its commands and their options | New commands and options | | App identity | Bundle ID `com.TablePro`, and `Contents/MacOS/tablepro-mcp` inside the bundle | Nothing | | Install location | Not covered | Anything. Find the app by bundle ID | From 523ed069ab7114976a4eef86be81caec166f1d86 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Sun, 8 Nov 2026 22:56:58 +0700 Subject: [PATCH 3/4] docs(integrations): rewrite command line guides --- customization/general-settings.mdx | 4 +- developers/pairing.mdx | 25 +-- developers/tokens.mdx | 3 +- developers/versioning.mdx | 19 ++- features/query-history.mdx | 2 +- integrations/index.mdx | 7 +- integrations/mcp-clients.mdx | 42 ++++- integrations/terminal.mdx | 238 ++++++++++------------------- linux/command-line.mdx | 201 +++++++++++------------- linux/connect.mdx | 2 +- linux/troubleshooting.mdx | 2 +- snippets/cli-exit-status.mdx | 12 +- snippets/cli-output-formats.mdx | 19 ++- snippets/cli-schema-commands.mdx | 29 ++-- snippets/stability-matrix.mdx | 2 +- 15 files changed, 289 insertions(+), 318 deletions(-) diff --git a/customization/general-settings.mdx b/customization/general-settings.mdx index 8d47a3a3..9e391723 100644 --- a/customization/general-settings.mdx +++ b/customization/general-settings.mdx @@ -56,11 +56,11 @@ Older servers have neither: MySQL before 5.7.8, MariaDB before 10.1.1. A stateme ## Command line tool -Shows whether `/usr/local/bin/tablepro` links to this copy of the app, with the Terminal line that links or removes it. A copy running from the disk image or another read-only volume shows no line and asks to be moved to Applications first. The command opens database URLs and files in the app, and runs queries, browses schemas and exports tables from a shell. See [Terminal](/integrations/terminal). +**Command Line** shows whether the shell command links to this copy of the app. Copy its Terminal line to install or remove the link. See [Terminal](/integrations/terminal#install) for installation and commands. ## Trusted links -External links you chose to always allow, each with **Forget**, plus **Forget All**. Only a database on this machine can be trusted; a link to a remote host asks every time. +Use **Forget** to remove one saved link approval, or **Forget All** to remove them all. See [Trusting a link](/integrations/terminal#trusting-a-link) for which links qualify and when they still ask. ## Software update diff --git a/developers/pairing.mdx b/developers/pairing.mdx index 15dfeed1..8c988e96 100644 --- a/developers/pairing.mdx +++ b/developers/pairing.mdx @@ -100,8 +100,8 @@ Three constraints decide whether TablePro accepts the request at all: name, such as `smb://`, `ssh://` and `webcal://`. The exchange endpoint takes no bearer token: the single-use code plus the verifier is the credential. -It, [the revoke route](#revoking-a-token) and `/mcp` are the only paths the server serves, and all -three accept `POST` only. +The public HTTP routes are `/v1/integrations/exchange` and `/mcp`; both accept `POST` only. +The bundled command also uses a [private revocation route](#revoking-a-token). ## Response modes @@ -162,17 +162,22 @@ request, not a grant. **Deny** is the default button: Return and Escape both den takes a click. The sheet does not take focus from another app; TablePro's Dock icon bounces instead. Approving mints the token, holds the plaintext against a one-time code for 5 minutes, and opens the -redirect. Pairing again mints a second token rather than replacing the first, so an extension that -re-pairs should [revoke](#revoking-a-token) its old one, or the user revokes it under -**Settings > MCP > Authentication**. +redirect. Pairing again creates a separate token. Retire an old token through +[revocation](#revoking-a-token) once the client uses its replacement. ## Revoking a token -`tablepro unpair` revokes its own token with an [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) -request to `/v1/integrations/revoke`. The route listens on the -[private socket](/developers/mcp-protocol#local-socket-and-handshake) only, which is not under the -[contract](/developers/versioning#what-is-not-under-the-contract). Revoke any other client's token in -**Settings > MCP > Authentication**. +Revoke a client's token in **Settings > MCP > Authentication**. For the bundled macOS command, +use [`tablepro unpair`](/integrations/terminal#status-and-pairing). + +The command sends `POST /v1/integrations/revoke` over the private Unix socket, with a form-encoded +`token` field. The route does not exist on the TCP listener and is outside the +[stability contract](/developers/versioning#what-is-not-under-the-contract). Do not use it as a +public client API. + +A successful response is `200 {}`, including for an unknown or already revoked token. A `503` +means revocation was not saved: the token remains valid. The server refuses the stdio bridge +credential with `400 unsupported_token_type`. ## Security properties diff --git a/developers/tokens.mdx b/developers/tokens.mdx index 8275e167..6881bffd 100644 --- a/developers/tokens.mdx +++ b/developers/tokens.mdx @@ -65,7 +65,8 @@ Revoking cancels every request that token has in flight and clears the connectio **Disconnect** in the Connected Clients list revokes that client's token. It is not a soft disconnect: the client has to pair again or be given a new token. -`tablepro unpair` revokes its own token. See [Revoking a token](/developers/pairing#revoking-a-token). +For the bundled macOS command, follow [Status and pairing](/integrations/terminal#status-and-pairing) +to replace or remove its token. Its [revocation route](/developers/pairing#revoking-a-token) is private. ## The stdio bridge token diff --git a/developers/versioning.mdx b/developers/versioning.mdx index 9f0babd5..22f3c758 100644 --- a/developers/versioning.mdx +++ b/developers/versioning.mdx @@ -83,13 +83,16 @@ Treat the port as a setting that defaults to `23508`; the pane's **Status** row ### The tablepro command and the app's identity -- `tablepro`, once installed from **Settings > General**, stays at `/usr/local/bin/tablepro`, and - its commands and options keep their names and meanings. -- Given database URLs, `tablepro://` links, `.sql` files or database files, `tablepro` opens them in - the copy of TablePro it ships in, or in the copy already running. With no argument it opens the app. -- The bundle ID stays `com.TablePro`. -- The MCP bridge stays at `Contents/MacOS/tablepro-mcp` inside the app bundle. -- Where the bundle sits is up to the user. [Find the app](/developers#find-the-app) by bundle ID. +The documented commands, options and [exit statuses](/integrations/terminal#exit-status) keep their +names and meanings within a major version. New commands and options may appear. Use the reference +for your platform: [macOS](/integrations/terminal) or [Linux](/linux/command-line). + +On macOS, the command ships at `Contents/SharedSupport/bin/tablepro` inside the app bundle. +The [install command](/integrations/terminal#install) links it into `/usr/local/bin`. Opening files +or URLs targets that app, or a copy already running. No arguments opens the app. + +The bundle ID stays `com.TablePro`, and the MCP bridge stays at `Contents/MacOS/tablepro-mcp`. +The install folder is the user's choice; [find the app](/developers#find-the-app) by bundle ID. ## Breaking changes before 1.0 @@ -111,6 +114,8 @@ These can change in any release, without notice: - Transport framing, internal message routing, and any HTTP path other than `/mcp` and `/v1/integrations/exchange`. +- `/v1/integrations/revoke`, used by the bundled macOS command over the private socket. It is not + available through public HTTP. See [Revoking a token](/developers/pairing#revoking-a-token). - The [handshake file and private socket](/developers/mcp-protocol#local-socket-and-handshake). Use the bundled `tablepro-mcp` bridge, which finds the server on its own, or connect over HTTP to the port on the **Status** row in **Settings > MCP**, `23508` by default. diff --git a/features/query-history.mdx b/features/query-history.mdx index 66fa0c8a..f1c7680e 100644 --- a/features/query-history.mdx +++ b/features/query-history.mdx @@ -49,7 +49,7 @@ Search matches partial words, so `cust` finds `customers`. Several words must al | AI and MCP | Queries run by an AI assistant or an MCP client | | AppleScript | Queries run by [a script](/developers/applescript) | | Shortcuts | Queries and inserts run by a [Shortcuts action](/integrations/shortcuts) | -| Command Line | Queries run by [`tablepro query`](/integrations/terminal#run-a-query) | +| Command Line | Queries from the [macOS command](/integrations/terminal#run-a-query) | **My Queries**, the default, is Editor and Explain. Add **Table Browsing** to see what the app sent while you clicked around a table, **Structure Changes** to review what altered a schema and when. diff --git a/integrations/index.mdx b/integrations/index.mdx index 33a4ed3a..89fc29e7 100644 --- a/integrations/index.mdx +++ b/integrations/index.mdx @@ -4,10 +4,7 @@ sidebarTitle: Overview description: Use TablePro from AI clients, Raycast, the terminal, DDEV and iOS Shortcuts --- -AI clients, the Raycast extension and the `tablepro` command query your databases through the -[MCP server](/features/mcp), so its limits, tokens and activity log, all reached from -**Settings > MCP**, apply to them. Opening a link or a file from the terminal, DDEV and iOS Shortcuts -work without it. +Use the [macOS command](/integrations/terminal) or [Linux command](/linux/command-line) for shell scripts. Use an MCP client for an AI assistant, or a link to open a connection in the app. @@ -17,7 +14,7 @@ work without it. Search connections, browse schemas and run SQL from Raycast. - Open database URLs and files, and query, browse and export a connection, with the `tablepro` command. + Install the macOS command and run queries, browse connections or export tables. Open a project's database with `ddev tablepro`. diff --git a/integrations/mcp-clients.mdx b/integrations/mcp-clients.mdx index 23cb0f0b..7a81be6e 100644 --- a/integrations/mcp-clients.mdx +++ b/integrations/mcp-clients.mdx @@ -154,7 +154,47 @@ Zed, in `~/.config/zed/settings.json`: Claude Desktop starts MCP servers only as commands, so it needs a stdio-to-HTTP bridge of its own to reach this server. -The Linux server has eleven tools: `list_connections`, `connect`, `list_databases`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`, `browse_table`, `count_rows`, `execute_query` and `export_data`. The schema tools, `execute_query` and `export_data` take an optional `database`, which reaches only a database already open in the connection's window: its own, or one added with **Open Database…**. `execute_query` with `read_only: true` refuses any statement that is not a read. `export_data` returns tables as CSV, JSON or SQL `INSERT` statements, up to 1,000 rows each. Each connection's **External Clients** level decides what a client may do there: **Blocked**, **Read Only** (the default) or **Read & Write**. A write runs only after you click **Run** in the connection's window. **Regenerate Access Token…** turns the old token away at the next request, so paste the new one into every client. +### Linux tools + +Start with `list_connections` and pass an id from its result as `connection_id`. Call `connect` for +a closed connection; a `connecting` result means the user may need to answer a prompt in the app. +Call it again to check for `open`. + +Arguments marked `?` are optional. Unknown arguments are rejected. + +| Tool | Arguments | Result | +|---|---|---| +| `list_connections` | None | Saved connections visible to clients, their open state, external access and Safe Mode | +| `connect` | `connection_id` | Opens the connection in a window; returns `connecting` or `open` | +| `list_databases` | `connection_id` | Databases and which one is current; unsupported on engines with no database listing | +| `list_schemas` | `connection_id`, `database?` | Schemas, with default and system flags | +| `list_tables` | `connection_id`, `database?`, `schema?` | Tables and views | +| `describe_table` | `connection_id`, `table`, `database?`, `schema?` | Columns, indexes, foreign keys and a row count where available | +| `get_table_ddl` | `connection_id`, `table`, `database?`, `schema?` | Statements that create the table | +| `browse_table` | `connection_id`, `table`, `schema?`, `filters?`, `logic?`, `sort?`, `limit?` | Filtered and sorted rows | +| `count_rows` | `connection_id`, `table`, `schema?`, `filters?`, `logic?` | Exact count of matching rows | +| `execute_query` | `connection_id`, `query`, `database?`, `read_only?`, `max_rows?`, `timeout_seconds?` | One statement's results, or one SQL Server batch's results | +| `export_data` | `connection_id`, `format`, `tables`, `database?`, `schema?`, `max_rows?` | CSV, JSON or SQL `INSERT` text for each table, with row counts and truncation flags | + +`database` defaults to the connection's own database. An override must already be open beside it +through **Open Database…**. `schema` defaults to the connection's default schema. Pass table and +column names without SQL quotes. `execute_query` takes no `schema`; qualify names in the SQL. + +`read_only` defaults to `false`. Set it to `true` to refuse anything but a read before asking for +write approval. Query size, row and timeout limits are the same as the +[Linux command](/linux/command-line#run-a-query); its [query rules](/linux/command-line#what-a-query-may-do) +also apply. `browse_table.limit` and `export_data.max_rows` use the query row limits. +`export_data` takes the [export formats and table limit](/linux/command-line#export) and returns text +in the response, without writing a file. + +A filter has `column`, `operator`, and either `value` or `values`. Operators are `eq`, `not_eq`, `lt`, +`lt_eq`, `gt`, `gt_eq`, `contains`, `starts_with`, `ends_with`, `like`, `not_like`, `ilike`, `is_null`, +`is_not_null`, `in`, `not_in` and `between`. Use `values` for lists and the two bounds of `between`; +null checks need neither. `logic` is `and` by default, or `or`. Each sort entry has `column` and an +optional `direction`: `ascending` by default, or `descending`. + +After **Regenerate Access Token…**, update the token in each MCP client. The +[Linux command](/linux/command-line#check-status) reads the replacement itself. ## HTTP transport diff --git a/integrations/terminal.mdx b/integrations/terminal.mdx index 056e79d5..0a26e019 100644 --- a/integrations/terminal.mdx +++ b/integrations/terminal.mdx @@ -1,197 +1,130 @@ --- title: Terminal -description: Open database URLs and files in TablePro from a shell, and query, browse and export a connection from a script +description: Install and use the macOS tablepro command for queries, schema browsing and exports --- import CliExitStatus from "/snippets/cli-exit-status.mdx"; import CliOutputFormats from "/snippets/cli-output-formats.mdx"; import CliSchemaCommands from "/snippets/cli-schema-commands.mdx"; -`open "mysql://…"` goes to whichever app claims the `mysql://` scheme, and with another database -client installed that may not be TablePro. Name TablePro instead, either by bundle identifier or -through the `tablepro` command: +Open files and connection links in the app with `tablepro`, or run a command to print database results in your shell. Queries, browsing and exports use the app's MCP server and its access rules. -```bash -open -b com.TablePro "mysql://root@127.0.0.1:3306/shop" -tablepro "postgresql://user:pass@127.0.0.1:5432/app?table=orders" -``` - -Any [connection URL](/connections/urls) works, including its query parameters. TablePro uses a saved -connection when one matches on type, host, port, database and user; otherwise the session is -temporary and never written to disk. Running `tablepro` with no argument opens the app and nothing else. - - -TablePro for Linux ships the same command with the app. See [Command line](/linux/command-line). - +For Linux, see [Command line](/linux/command-line). -## Add the tablepro command to your PATH +## Install -The command ships inside the app at `TablePro.app/Contents/SharedSupport/bin/tablepro` and works -with the copy it ships in: files and links open there, and a command that needs TablePro running -starts that copy. A copy already running from another folder receives them instead. Link the command -into `/usr/local/bin` once: +With the app in `/Applications`, run this line in Terminal: ```bash -sudo mkdir -p /usr/local/bin && sudo rm -f /usr/local/bin/tablepro && sudo ln -s /Applications/TablePro.app/Contents/SharedSupport/bin/tablepro /usr/local/bin/tablepro +sudo mkdir -p '/usr/local/bin' && sudo rm -f '/usr/local/bin/tablepro' && sudo ln -s '/Applications/TablePro.app/Contents/SharedSupport/bin/tablepro' '/usr/local/bin/tablepro' ``` -`sudo` asks for your password in Terminal. TablePro itself never writes outside its own folders and -never asks for an administrator password. **Settings > General > Command Line** prints the same line -with the path of the copy you are running, and reads **Linked** once the link is in place. Any other -directory on your `PATH` works too, and one you own needs no `sudo`. +For a different location, copy the line from **Settings > General > Command Line**. It links `/usr/local/bin/tablepro` to the command inside that copy of the app. Enter your administrator password in Terminal when `sudo` asks. -A copy opened from the mounted disk image, or one macOS still runs from where it was downloaded (App -Translocation), sits on a read-only volume. Settings shows no line for it and asks you to move -TablePro to Applications. Move it, open it from there, and the line appears. +A copy on a read-only volume, including a mounted disk image or an App Translocation location, offers no install line. Move the app to Applications and open it there first. - - Command Line section in TablePro settings with the Terminal command to link tablepro - Command Line section in TablePro settings with the Terminal command to link tablepro + + Command Line settings showing the link status and a Terminal command + Command Line settings showing the link status and a Terminal command -To remove it, run `sudo rm /usr/local/bin/tablepro`. The link follows the app, so updating TablePro -updates the command; move the app and the link needs making again. +App updates also update the command. If you move the app, recreate the link. To remove the link: -`tablepro --version` prints the version of the app the command ships in. `tablepro --help` lists the -commands, and `tablepro help query` or `tablepro query --help` explains one. +```bash +sudo rm /usr/local/bin/tablepro +``` -## Open a file +Use `tablepro --help` to list commands, `tablepro help query` for a command's options, and `tablepro --version` for the bundled app's version. -Files route the same way, whether double-clicked in Finder or passed on the command line: +## Open files and links ```bash +tablepro tablepro schema.sql -tablepro app.db +tablepro app.sqlite3 +tablepro "postgresql://ada@127.0.0.1:5432/shop?table=orders" ``` -- `.sql`, `.psql` and `.pgsql` open in a query tab on the current connection. A window already - holding that file comes to front. With no connection open, the file waits until you connect. -- Database files open a connection to the file itself and save nothing: `.db`, `.db3`, `.s3db`, - `.sl3`, `.sqlite`, `.sqlite3` and `.sqlitedb` open with SQLite, `.duckdb` and `.ddb` with the - DuckDB plugin. A window already connected to that file comes to front instead of a second one - opening. +With no arguments, open the app. Files and links go to the copy the command ships in, or to a copy already running. + +SQL files (`.sql`, `.psql`, `.pgsql`) open in an editor tab without running. With no connection open, they wait until you connect. SQLite and DuckDB files open a temporary connection. An already open file brings its window forward. + +Use any [connection URL](/connections/urls) or [tablepro link](/developers/url-scheme). A matching saved connection is reused; otherwise the session is temporary. See [Trusting a link](#trusting-a-link) for the consent prompt. -`tablepro ` is short for `tablepro open `. A word that is neither an existing file nor a -URL opens nothing and exits 2, so `tablepro qeury` fails instead of starting the app. A file named -like a command, such as `tables`, opens with `./tables` or `tablepro open tables`. +`tablepro open ` is the explicit form. Use `tablepro open tables` or `tablepro ./tables` for an existing file named like a command. A target must be an existing file or a URL with a scheme; a typo such as `tablepro qeury` exits 2. ## Run a query +Turn on **Settings > MCP > Enable MCP Server** and [pair the command](#status-and-pairing) before running scripts. + ```bash -tablepro query --connection Staging --format csv "SELECT id, email FROM users LIMIT 5" -tablepro query -c Staging -f report.sql > report.csv -echo "SELECT count(*) FROM orders" | tablepro query -c Staging --format json +tablepro query -c Staging "SELECT id, email FROM users LIMIT 5" +tablepro query -c Staging -f report.sql --format csv > report.csv +printf '%s\n' 'SELECT count(*) FROM orders' | tablepro query -c Staging --format json ``` -`--connection` takes a saved connection's name or its id, and `tablepro connections` lists both. The -SQL comes from the argument, from `-f `, or from standard input, and `-f -` reads standard -input even at a terminal, until `Ctrl+D`. Rows go to standard output, messages and errors to -standard error. - -SQL that starts with a dash, such as a leading `--` comment, goes after `--`, which ends the options: +Choose one SQL source: an argument, `-f` (`--file`), or piped input. `-f -` also reads from a terminal until `Ctrl+D`. Put SQL that starts with a dash after `--`: ```bash tablepro query -c Staging -- "-- weekly report SELECT count(*) FROM orders" ``` -| Option | | +| Option | Use | |---|---| -| `--database`, `--schema` | Where the statement runs. Without them, the connection's current database and schema | -| `--format` | `csv`, `tsv`, `json`, `jsonl` or `table`. `table` on a terminal, `csv` into a pipe or a file | -| `--limit` | Rows to return. Defaults to **Default row limit** under **Settings > MCP**, 500, and stops at **Maximum row limit** | -| `--timeout` | Seconds the statement may run, 1 to 300. Defaults to **Query timeout** under **Settings > MCP**, 30 | -| `--read-only` | Refuse any statement that is not a read, even on a connection set to **Read & Write** | - -A result cut short by `--limit` says so on standard error. - -### What a query may do +| `-c`, `--connection` | Saved connection name or id; find it with the [browse commands](#browse-a-connection) | +| `--database`, `--schema` | Override the connection's current database or schema | +| `--format` | Choose an [output format](#output-formats) | +| `--limit` | Set the returned row count, within **Maximum row limit** in **Settings > MCP** | +| `--timeout` | Set the statement timeout in seconds | +| `--read-only` | Refuse any statement that is not a read | -A query clears the same gates as any [MCP client](/features/mcp#connection-access), and so does -every other command that names a connection: +Without a limit or timeout, the [MCP defaults](/features/mcp#server-configuration) apply. A result cut short prints a message on standard error. -- The connection's **External Clients** level: **Blocked** hides it, **Read Only** refuses writes. -- A connection whose AI policy is **Never** is hidden as well. A hidden connection reads as unknown, - by name or by id, and the command exits 2. -- The first query on each connection asks you, as often as **Approval** under **Settings > MCP** says. -- [Safe Mode](/features/safe-mode) confirms or authenticates writes on your Mac. -- `DROP` and `TRUNCATE` are refused. Run them in TablePro. -- One statement per run. A SQL Server script runs batch by batch at its `GO` lines and prints - every result set, separated by a blank line, or in JSON as one array per result set. - -Every statement goes to the execution audit log, and to the [history drawer](/features/query-history#sources) -under **Command Line**. - -## Browse a schema - -```bash -tablepro connections --format json -tablepro databases -c Staging -tablepro tables -c Staging --database app --schema public -tablepro describe -c Staging --schema public orders -tablepro describe -c Staging --ddl orders -``` +## Browse a connection -## Export a table +## Export ```bash tablepro export -c Staging --format csv orders > orders.csv -tablepro export -c Staging --format sql --limit 5000 orders > orders.sql +tablepro export -c Staging --schema public --format sql --limit 5000 orders users > shop.sql ``` -`--format` is `csv`, `json` or `sql`, and `sql` writes `INSERT` statements in the connection's own -quoting. Each table stops at **Default row limit** under **Settings > MCP**, 500 unless you change -it, and `--limit` raises that as far as **Maximum row limit**. A table cut short says so on standard -error. For every row, use [Export](/features/import-export) in the app. +Choose `csv`, `json` or `sql`; `--format` is required. SQL output contains `INSERT` statements in the engine's dialect. Use `--database` and `--schema` to select where the tables live. + +The [query row limit](#run-a-query) also applies to each exported table. `--limit` overrides it, and standard error names any table cut short. For a full export, use [Import & Export](/features/import-export) in the app. -A table name takes letters, digits and underscores, optionally as `schema.table`. For any other -name, run `tablepro query` with `--format csv` or `--format json`. +Table names accept letters, digits and underscores, with dots between parts such as `public.orders`. For other names, quote the name in SQL and use `query --format csv` or `query --format json`. -## Pair the command +## Status and pairing -The command reaches TablePro through its MCP server, so turn on **Enable MCP Server** under -**Settings > MCP** first. With it off, every command that reads from TablePro exits 3. When TablePro -is not running, the command starts its own copy in the background, with no window. +`tablepro status` checks the app, MCP server and pairing without starting the app or asking for approval. Add `--format json` for scripts. It exits 0 when ready, 1 when the app cannot be reached, and 3 when the server is off or the command is not paired. + +Other commands that need the server start the app if needed. The MCP server must already be enabled in Settings. - - Any other command that reads from TablePro starts the same pairing the first time. TablePro asks - **Allow tablepro command to access TablePro?** + + Run `tablepro pair` in Terminal. A query or browse command also starts pairing when no token is stored and standard error is a terminal. - - The sheet starts at **Read Only**. Pick **Read & Write** if your scripts write, and limit the - connections or set an expiry if you want. + + The sheet starts at **Read Only**. Choose **Read & Write** for scripts that change data. Select the allowed connections and expiry, then click **Approve**. - - Your browser opens a page saying the command is paired. Close it. A command you ran continues. + + Close the browser confirmation tab. The token is stored in your login Keychain. If a command started pairing, it continues. -The token lives in your login Keychain. Revoke it under **Settings > MCP** and the next run exits 3; -the run after that asks to pair again. A run whose standard error is not a terminal, such as a cron -job, exits 3 instead of opening the sheet. `tablepro pair` replaces the stored token with a new one; -run `tablepro unpair` first to revoke the old one. - -### Check or remove the pairing +An unattended command with no token exits 3. A rejected or expired token is removed and that run exits 3; run `tablepro pair` again. Pairing again stores a replacement and asks the server to revoke the previous token. If that fails, the command prints a warning; revoke the old token in Settings. -`tablepro status` shows the path and version of the copy the command belongs to, whether TablePro is -running, whether the MCP server is on, and whether the command is paired. It never starts TablePro -and never asks to pair. It exits 0 when a command can run now, 1 when TablePro is not running or -cannot be reached, and 3 when the server is off or the command is not paired. - -`tablepro unpair` revokes the token in TablePro, then deletes it from the Keychain. When TablePro -cannot be reached, it deletes only the Keychain copy and says so. The token then stays active under -**Settings > MCP > Authentication** until you revoke it there. +`tablepro unpair` revokes the token and removes its Keychain copy. If the server cannot be reached, only the local copy is removed; revoke the remaining token in **Settings > MCP > Authentication**. If the server reports that it could not save the revocation, the local token stays for another attempt. These failures exit 1. ## Shell completion -`tablepro completion zsh`, `bash` or `fish` prints a script that completes commands, options and -`--format` values. Connection names do not complete. Save the script where your shell loads it: +Generate the script for your shell. It completes commands, options and format names, but does not look up connection names. - ```bash zsh mkdir -p ~/.zsh/completion tablepro completion zsh > ~/.zsh/completion/_tablepro @@ -204,55 +137,52 @@ echo 'source ~/.bash_completions/tablepro.bash' >> ~/.bash_profile ``` ```bash fish +mkdir -p ~/.config/fish/completions tablepro completion fish > ~/.config/fish/completions/tablepro.fish ``` - -zsh also needs the folder on its function path. Add these lines to `~/.zshrc` once, then open a new -shell: +For zsh, add these lines to `~/.zshrc` once: ```bash fpath=(~/.zsh/completion $fpath) autoload -U compinit && compinit ``` -Run the command again after an update that adds commands. +Open a new shell. Generate the script again after an update adds commands or options. + +## Output formats + + + +Query values arrive as text or NULL. Binary values are Base64. ## Exit status -On the Mac, 3 also covers a command that is not paired and cannot ask, and a revoked pairing. +Pairing refusal or expiry also exits 3. See [Status and pairing](#status-and-pairing) for the status and unpair cases. -## Output formats +## What a query may do - +The command follows the [MCP connection access rules](/features/mcp#connection-access): -Every value is text, as in the grid. Binary columns come out as Base64. Two columns with the same -name become `name` and `name_2` in JSON. +- **Blocked** connections, an AI policy of **Never**, and connections outside the token's allowlist are hidden. Naming one exits 2. +- Writes need both a **Read & Write** token and **Read & Write** external access. `--read-only` still refuses them. +- **Approval** in **Settings > MCP** controls connection approval. [Safe Mode](/features/safe-mode) also applies to writes. +- Destructive statements such as `DROP`, `TRUNCATE`, `ALTER ... DROP` and `DELETE` without `WHERE` are refused. Run them in the app. Statements that access files or run server-side code are also refused. + +Send one statement per query. SQL Server also accepts a script split at `GO` lines and returns each result set. Executed queries enter the audit log and [query history](/features/query-history#sources). ## Trusting a link -The first time a link connects, TablePro asks: **Open External Database Connection?**, showing the -host, user and database. This is what stops a web page from opening a connection behind your back. +A database link asks **Open External Database Connection?** before connecting. Check the host, user and database before approving. -For a database on your own machine (`localhost`, `127.0.0.1`, `::1`, or any `127.x.x.x` address) the -alert adds **Always Allow**. Choose it and that database stops asking, which is what makes -[`ddev tablepro`](/integrations/ddev) a one-step command. Trust is keyed on database type, host, -database name, user and the URL's `name` parameter, not the port, so a tool that picks a new port on -each start stays trusted. +For a local connection without SSH or a filter, **Always Allow** remembers the database type, host, database, user and URL `name`. Local hosts include `localhost`, `::1` and `127.x.x.x`. A local socket grant also includes its path. The port is excluded, so a development server may change ports without asking again. Remote hosts and SSH links ask every time. - - Alert asking to confirm an external database link, with Always Allow for local databases - Alert asking to confirm an external database link, with Always Allow for local databases + + External connection alert showing the target database and approval buttons + External connection alert showing the target database and approval buttons - -A link to a remote host asks every time. Only a database on this machine can be trusted. - - -**Settings > General > Trusted Links** lists what you have trusted, with **Forget** per entry and -**Forget All**. Two things still prompt even on a trusted connection: a link carrying a filter -(`?query=`, `?condition=` or `?raw=`) confirms the filter, and a connection with a pre-connect script -shows the script. +Remove a grant with **Forget** or **Forget All** under **Settings > General > Trusted Links**. A trusted link still asks before applying a filter (`query`, `condition` or `raw`) or running a pre-connect script. diff --git a/linux/command-line.mdx b/linux/command-line.mdx index cd84e6b9..de391535 100644 --- a/linux/command-line.mdx +++ b/linux/command-line.mdx @@ -1,6 +1,6 @@ --- title: Command line -description: Run queries, browse schemas, export tables and open connection URLs from a terminal with TablePro for Linux +description: Query, browse and export saved connections from a Linux shell tag: "Beta" --- @@ -8,171 +8,152 @@ import CliExitStatus from "/snippets/cli-exit-status.mdx"; import CliOutputFormats from "/snippets/cli-output-formats.mdx"; import CliSchemaCommands from "/snippets/cli-schema-commands.mdx"; -The `tablepro` that starts the app is also its command line. A first word that names a command runs -in the terminal and prints there; a file, a URL or no argument at all opens the app. +Use the same executable to launch the app or print database results in a terminal. Files and links open windows; commands such as `query` and `export` write to standard output. - +## Set up -```bash .deb and .rpm -tablepro query -c Staging "SELECT id, email FROM users LIMIT 5" +The command ships with the app. Choose the form for your installation: + + +```bash .deb or .rpm +tablepro --help +tablepro help query ``` ```bash Flatpak -flatpak run app.tablepro.TablePro query -c Staging "SELECT id, email FROM users LIMIT 5" +flatpak run app.tablepro.TablePro --help +flatpak run app.tablepro.TablePro help query ``` - -The rest of this page writes `tablepro`. For Flatpak, put `flatpak run app.tablepro.TablePro` in its -place, or add `alias tablepro='flatpak run app.tablepro.TablePro'` to your shell's startup file. -`tablepro --help` lists the commands, `tablepro help query` explains one, and `tablepro --version` -prints the app's version. - -## Before the first command - -Commands go through the app's [MCP server](/integrations/mcp-clients#tablepro-for-linux), so two -things have to hold: - - - - The server runs only while the app is open, and a command never starts it. With the app closed, - a command exits 1 and says TablePro is not running. - - - Turn on **Preferences > MCP > Enable MCP Server**. With it off, a command exits 3. - - +Examples on this page use `tablepro`. For Flatpak, replace it with `flatpak run app.tablepro.TablePro`. `--version` prints the app version. -`tablepro status` checks both without starting anything. It exits 0 when a command can run now, 1 -when TablePro is not running, and 3 when the server is off. +Before querying, open the app and turn on **Preferences > MCP > Enable MCP Server**. Commands never start the app. Each run reads the access token from the app's keyring, so there is no `pair` or `unpair` command. Use the command from the same installation as the running app; native and Flatpak installations have separate token storage. -There is no pairing step. Each run reads the server's access token from the keyring where the app -keeps it, so **Regenerate Access Token…** needs nothing on the command line. A Flatpak command reads -the sandbox's own copy: run the command from the same installation as the app, since a native -`tablepro` cannot read a Flatpak app's token, nor the other way round. - -## Open files and connection URLs +## Open files and links ```bash +tablepro tablepro app.sqlite3 sales.duckdb -tablepro "postgresql://ada@db.example.com:5432/shop" tablepro --new-window schema.sql +tablepro "postgresql://ada@db.example.com:5432/shop" ``` -A database file opens as a session, as in [SQLite and DuckDB files](/linux/connect#sqlite-and-duckdb-files), -and a `.sql` file opens in an editor tab. `--new-window`, or `-n`, opens them in a new window. - -`tablepro ` is short for `tablepro open `. A word that is neither an existing file nor a -URL opens nothing and exits 2. A file named like a command, such as `tables`, opens with `./tables` -or `tablepro open tables`. +With no arguments, launch the app. Database files open as [SQLite or DuckDB sessions](/linux/connect#sqlite-and-duckdb-files). A SQL file opens an editor tab without running. `-n` (`--new-window`) requests a new window. -### Connection URLs +`tablepro open ` also opens a file or URL. Use `tablepro open tables` or `tablepro ./tables` for an existing file named like a command. A word that is neither an existing file nor a URL exits 2. -These schemes open in TablePro from a terminal, and from a link in a browser or any other app: - -| Engine | Schemes | -|---|---| -| PostgreSQL | `postgresql`, `postgres` | -| MySQL and MariaDB | `mysql`, `mariadb`, `mysqlx` | -| SQL Server | `sqlserver`, `mssql` | -| ClickHouse | `clickhouse`, `ch` | -| Cassandra and ScyllaDB | `cassandra`, `cql`, `scylla`, `scylladb` | -| Redis | `redis`, `rediss`, `valkey`, `valkeys` | -| MongoDB | `mongodb`, `mongodb+srv` | -| SQLite | `sqlite`, `sqlite3` | -| DuckDB | `duckdb` | - -A URL that matches a saved connection asks before opening it. `Enter` and `Escape` both cancel, so -click **Open** to go ahead. Any other URL opens the connect dialog filled from it: check the host, -user and database, then click **Connect**, which saves the connection once it connects. A password in -the URL goes to the **Password** row only, and is never logged or shown. +Links always need consent. See [Connection links](#connection-links) for schemes and prompts. ## Run a query ```bash -tablepro query -c Staging --format csv "SELECT id, email FROM users LIMIT 5" -tablepro query -c Staging -f report.sql > report.csv -echo "SELECT count(*) FROM orders" | tablepro query -c Staging --format json +tablepro query -c Staging "SELECT id, email FROM users LIMIT 5" +tablepro query -c Staging -f report.sql --format csv > report.csv +printf '%s\n' 'SELECT count(*) FROM orders' | tablepro query -c Staging --format json ``` -`-c` takes a saved connection's name or id, and `tablepro connections` lists both. The SQL comes -from the argument, from `-f `, or from standard input, and `-f -` reads standard input even at -a terminal. Under Flatpak, `-f` reads files in your home folder, `/media`, `/run/media` and `/mnt`; -pass any other file on standard input. +Pass SQL as an argument, with `-f` (`--file`), or on standard input. `-f -` reads from a terminal until `Ctrl+D`. For a file outside the Flatpak sandbox's access, redirect standard input from your host shell. -SQL that starts with a dash, such as a leading `--` comment, goes after `--`, which ends the options: +Put SQL beginning with a dash after `--`: ```bash tablepro query -c Staging -- "-- weekly report SELECT count(*) FROM orders" ``` -| Option | | +| Option | Use | |---|---| -| `--database` | A database already open in the connection's window: its own, or one added with **Open Database…** on its sidebar row. Without it, the connection's own database | -| `--format` | `csv`, `tsv`, `json`, `jsonl` or `table`. `table` on a terminal, `csv` into a pipe or a file | -| `--limit` | Rows to return, 100 by default and 1,000 at most | -| `--timeout` | Seconds the statement may run, 1 to 300, 30 by default | -| `--read-only` | Refuse any statement that is not a read, even on a connection set to **Read & Write** | +| `-c`, `--connection` | Saved connection name or id; find it with the [browse commands](#browse-a-connection) | +| `--database` | Choose a database already open beside the connection through **Open Database…**; defaults to the connection's own database | +| `--format` | Choose an [output format](#output-formats) | +| `--limit` | Rows per result set, 100 by default; accepts 1 to 1,000 | +| `--timeout` | Seconds per statement, 30 by default; accepts 1 to 300 | +| `--read-only` | Refuse any statement that is not a read | -`query` has no `--schema`. Qualify table names in the SQL instead, as in `public.orders`. A result cut -short by `--limit` says so on standard error. +There is no `--schema` option on `query`. Qualify names in SQL, such as `public.orders`. A result cut short prints a message on standard error. The limit bounds returned rows, not how many rows a write changes. -### The connection has to be open +### Open the connection -A command that names a connection works on a session open in TablePro. Run from a terminal, it opens -a closed connection in a window, which may ask for the password, and waits up to 5 minutes for it to -connect. Run from a script or a cron job, where standard error is not a terminal, it exits 1 instead: -open the connection in TablePro first. +Commands use connections open in the app. With standard error attached to a terminal, a command opens a closed connection and waits up to five minutes. Answer any password prompt in the app. -### What a query may do +Without that terminal, a closed connection exits 1. Open it before starting an unattended script. Waiting for a connection that never opens also exits 1. -- The connection's **External Clients** level: **Blocked** hides it, so the command exits 2 as for an - unknown name. **Read Only**, the default, refuses writes. -- On **Read & Write**, a write runs only after you click **Run** in the connection's window. -- The connection's Safe Mode applies, as in the editor. -- One statement per run, or one batch on SQL Server. +## Browse a connection + + -## Browse a schema +As with `query`, `--database` selects only a database already open beside the connection. Omit `--schema` to use the connection's default schema. + +## Export ```bash -tablepro connections --format json -tablepro databases -c Staging -tablepro tables -c Staging --schema public -tablepro describe -c Staging --schema public orders -tablepro describe -c Staging --ddl orders +tablepro export -c Staging --format csv orders > orders.csv +tablepro export -c Staging --schema public --format sql --limit 1000 orders users > shop.sql ``` - +`--format` is required: choose `csv`, `json` or `sql`. SQL produces `INSERT` statements in the engine's dialect. Pass table names without SQL quotes; use shell quotes for spaces and `--schema` for the schema. `--database` follows the same rule as `query`. -`--database` reaches only a database already open in the connection's window, as for `query`. +The [query row limit](#run-a-query) also applies to each exported table. Set `--limit` to change it. A call accepts up to 20 tables, and standard error names any table cut short. For more rows, use [Export Rows…](/linux/data-grid#copy-and-export) in the app. -## Export a table +## Check status ```bash -tablepro export -c Staging --format csv orders > orders.csv -tablepro export -c Staging --format sql orders > orders.sql +tablepro status --format json ``` -`--format` is `csv`, `json` or `sql`, and `sql` writes `INSERT` statements in the engine's own -quoting. Each table stops at 1,000 rows, and a table cut short says so on standard error. For every -row, open the table and use [Export Rows…](/linux/data-grid#copy-and-export) on every saved row. +The report includes the app version, whether it is running, the MCP setting and port, whether a token was found, the server version and readiness. It does not start the app or open a connection. + +A ready server exits 0. A stopped or unreachable app exits 1. A disabled server or rejected token exits 3. After **Regenerate Access Token…** in Preferences, the next command reads the replacement automatically. ## Shell completion -The .deb and .rpm packages install completions for bash, zsh and fish. Open a new shell after -installing, and `Tab` completes commands, options and `--format` values; zsh needs `compinit` in -`~/.zshrc`, as most setups have. Connection names do not complete. Flatpak installs no completions. +The .deb and .rpm packages install bash, zsh and fish completions. Open a new shell after installing. For zsh, enable completion in `~/.zshrc` if it is not already enabled: + +```bash +autoload -U compinit && compinit +``` + +Flatpak installs no shell completions. `tablepro completion bash`, `tablepro completion zsh` and `tablepro completion fish` print scripts for a command named `tablepro`. These complete commands, options and format names, without looking up connection names. + +## Output formats + + -`tablepro completion bash`, `zsh` or `fish` prints the same script. +JSON preserves the value types returned by the server, including numbers and booleans. ## Exit status -On Linux, 1 also covers TablePro not running, and a closed connection when the command runs outside -a terminal. +A pipe closed by its reader, such as `| head`, exits 0. -## Output formats +## What a query may do - +A connection's **External Clients** setting applies to every command that uses it. **Blocked** hides the connection; naming it exits 2. **Read Only** is the default and refuses writes. + +With **Read & Write**, each write still needs **Run** in the connection's window. Safe Mode also applies; **Read-Only** refuses writes. `--read-only` refuses a write before it asks for approval. + +Send one statement, or one SQL Server batch, per query. The SQL text is limited to 100 KiB. A transaction left open by a write is rolled back when that call ends. + +## Connection links + +The desktop registers these schemes for links from browsers and other apps. They also work as command arguments. + +| Engine | Schemes | +|---|---| +| PostgreSQL | `postgresql`, `postgres` | +| MySQL and MariaDB | `mysql`, `mariadb`, `mysqlx` | +| SQL Server | `sqlserver`, `mssql` | +| ClickHouse | `clickhouse`, `ch` | +| Cassandra and ScyllaDB | `cassandra`, `cql`, `scylla`, `scylladb` | +| Redis | `redis`, `rediss`, `valkey`, `valkeys` | +| MongoDB | `mongodb`, `mongodb+srv` | +| SQLite | `sqlite`, `sqlite3` | +| DuckDB | `duckdb` | + +A `jdbc:` wrapper around a supported connection URL works from the command line, but has no desktop scheme registration. + +A link matching a saved connection asks before opening it. Click **Open** to continue; `Enter` and `Escape` cancel. Other links fill the connect dialog. Review the fields and click **Connect**; a successful connection is saved. + +A URL password fills the **Password** row. The full link is never logged or shown. There is no saved trust choice: local links need consent too. diff --git a/linux/connect.mdx b/linux/connect.mdx index 1c3fd631..156c3c03 100644 --- a/linux/connect.mdx +++ b/linux/connect.mdx @@ -125,7 +125,7 @@ An unknown or changed host key shows its SHA256 fingerprint before anything conn With **SQLite** or **DuckDB** picked, **Database file** replaces the server rows. **Choose…** opens an existing file, and **New Database…** creates the file when you connect. -A file also opens straight from Files, through **Open With** on a SQLite database, or from a terminal: +Open a file from Files, through **Open With** on a SQLite database, or with the [command line](/linux/command-line#open-files-and-links): ```bash tablepro app.sqlite3 sales.duckdb diff --git a/linux/troubleshooting.mdx b/linux/troubleshooting.mdx index dfc60d0c..b09c337c 100644 --- a/linux/troubleshooting.mdx +++ b/linux/troubleshooting.mdx @@ -115,7 +115,7 @@ Started from the desktop, the app writes its log to the journal: journalctl --user --boot | grep -i tablepro ``` -For a detailed log, quit the app first, since a second launch hands over to the running one and exits. Then start it from a terminal: +For a detailed log, quit the app first, since a second launch hands over to the running one and exits. Then start it with the [command for your installation](/linux/command-line#set-up): ```bash RUST_LOG=debug tablepro 2> tablepro.log diff --git a/snippets/cli-exit-status.mdx b/snippets/cli-exit-status.mdx index c9e4762b..9bc7a265 100644 --- a/snippets/cli-exit-status.mdx +++ b/snippets/cli-exit-status.mdx @@ -1,7 +1,7 @@ -| Exit status | Meaning | +| Status | Meaning | |---|---| -| 0 | Done, `--help`, `--version` and `completion` included | -| 1 | The database returned an error, TablePro could not be reached, or the output could not be written | -| 2 | A usage error: an unknown command or option, a missing `--connection`, a connection name or id the command cannot see, several statements in one run, no SQL, or a target that is neither a URL nor a file | -| 3 | Refused by a setting: the MCP server is off, the connection's **External Clients** level, Safe Mode, `--read-only`, or a declined prompt | -| 4 | Timed out: the statement ran past its timeout, or a prompt in TablePro went unanswered | +| 0 | Success, including help, version and completion output | +| 1 | Database, connection or output error | +| 2 | Invalid usage, SQL input or option value; unknown or ambiguous connection; missing file | +| 3 | Access refused, MCP server disabled, or approval declined | +| 4 | Query or server request timed out | diff --git a/snippets/cli-output-formats.mdx b/snippets/cli-output-formats.mdx index bd38806f..c7cbd0e3 100644 --- a/snippets/cli-output-formats.mdx +++ b/snippets/cli-output-formats.mdx @@ -1,10 +1,13 @@ -| Format | NULL | Other values | +Rows go to standard output. Errors, notices and truncation messages go to standard error. + +For queries, browse commands and `status`, the default is `table` when standard output is a terminal and `csv` otherwise. Set `--format` in scripts to choose it explicitly. + +| Format | Shape | NULL | |---|---|---| -| `csv` | An empty field. An empty string is `""` | Quoted when they hold a comma, a quote or a line break | -| `tsv` | An empty field | Tab, line break, carriage return and backslash written as `\t`, `\n`, `\r`, `\\` | -| `json` | `null` | An array of objects keyed by column name | -| `jsonl` | `null` | One object per line | -| `table` | `NULL` | Columns padded to line up, wide characters included. A control character shows as an escape, such as `\n` or `\x1B` | +| `csv` | Header and comma-separated rows; quotes protect commas, quotes and line breaks | Empty field; an empty string is `""` | +| `tsv` | Header and tab-separated rows; tabs, newlines, carriage returns and backslashes become `\t`, `\n`, `\r` and `\\` | Empty field | +| `json` | An array of objects keyed by column name | `null` | +| `jsonl` | One object per line | `null` | +| `table` | Aligned columns; control characters shown as escapes | `NULL` | -`query` and every listing command take the same `--format`: `table` on a terminal, `csv` into a pipe -or a file. Pass it in a script rather than relying on the terminal check. +Several result sets become an array of arrays in JSON, consecutive objects in JSONL, or blocks separated by a blank line in the other formats. Repeated column names get numbered JSON keys, such as `id` and `id_2`. diff --git a/snippets/cli-schema-commands.mdx b/snippets/cli-schema-commands.mdx index 7a0b0135..4105609d 100644 --- a/snippets/cli-schema-commands.mdx +++ b/snippets/cli-schema-commands.mdx @@ -1,11 +1,20 @@ -| Command | Prints | -|---|---| -| `connections` | Each saved connection's `name`, `id` and `type`, never a host, user or password. Connections the command may not reach are left out | -| `databases` | The connection's databases | -| `schemas` | The schemas in a database | -| `tables` | The tables and views in a schema | -| `describe
` | The table's columns, indexes and foreign keys. With `--ddl`, its `CREATE` statement | +```bash +tablepro connections --format json +tablepro databases -c Staging +tablepro schemas -c Staging --database shop +tablepro tables -c Staging --database shop --schema public +tablepro describe -c Staging --schema public orders +tablepro describe -c Staging --ddl orders +``` -Every command but `connections` takes `-c` with a saved connection's name or id. `schemas` takes -`--database`, and `tables`, `describe` and `export` take `--database` and `--schema`. Without them, -the connection's current database and schema apply. +| Command | Result | Scope options | +|---|---|---| +| `connections` | Saved connection names, ids and types; hidden connections are omitted | None | +| `databases` | Databases on the connection | `-c` | +| `schemas` | Schemas in a database | `-c`, `--database` | +| `tables` | Tables and views in a schema | `-c`, `--database`, `--schema` | +| `describe
` | Columns, indexes and foreign keys as separate result sets | `-c`, `--database`, `--schema` | + +`-c` is short for `--connection`. Pass a saved connection's name or id. If a name matches several connections, use an id from `connections`. + +All five commands accept `--format`. For `describe`, use `--ddl` to print the `CREATE` statement instead; it cannot be combined with `--format`. diff --git a/snippets/stability-matrix.mdx b/snippets/stability-matrix.mdx index 96208602..80b0b244 100644 --- a/snippets/stability-matrix.mdx +++ b/snippets/stability-matrix.mdx @@ -6,7 +6,7 @@ | AppleScript | Every term in the dictionary, with its four-character code | New classes, properties, commands, enumerators and optional parameters | | MCP server | Tools, resources, prompts, error codes, `/mcp`, `/v1/integrations/exchange`, and the default port `23508` | New tools, resources, prompts, codes, optional inputs and output fields | | Pairing | The `integrations/pair` link and its parameters, the code sent to `redirect`, and the exchange | New optional parameters | -| `tablepro` command on the Mac | `/usr/local/bin/tablepro`, its commands and their options | New commands and options | +| `tablepro` command | Documented commands, options and exit statuses on [macOS](/integrations/terminal) and [Linux](/linux/command-line) | New commands and options | | App identity | Bundle ID `com.TablePro`, and `Contents/MacOS/tablepro-mcp` inside the bundle | Nothing | | Install location | Not covered | Anything. Find the app by bundle ID | | Files, preferences and Keychain items the app writes | Not covered | Anything. See [what is not under the contract](/developers/versioning#what-is-not-under-the-contract) | From da9011544b4e479a84f25ebe587e24b3c51f731b Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Mon, 9 Nov 2026 03:11:36 +0700 Subject: [PATCH 4/4] docs(developers): describe per-request MCP peer checks --- developers/mcp-protocol.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/developers/mcp-protocol.mdx b/developers/mcp-protocol.mdx index f7c34ff4..26529804 100644 --- a/developers/mcp-protocol.mdx +++ b/developers/mcp-protocol.mdx @@ -78,7 +78,9 @@ actual path. Use the bundled bridge instead of hard-coding a path. This file is [outside the stable contract](/developers/versioning#what-is-not-under-the-contract). Before sending credentials, the bridge checks the file's owner and permissions, expiry, host process, -and socket ownership and location. It then calls `server/discover` over that socket and checks +and socket ownership and location. Before each request, the bridge and CLI check the connected +socket's `LOCAL_PEERPID` against the trusted handshake PID and recheck that process's executable. +It then calls `server/discover` over that socket and checks `app.tablepro/instanceId` against the handshake. A mismatch refuses the connection. A restart or socket failure requires a fresh trusted handshake; the bridge does not fall back to TCP.