docs/cli/overview.mdx
Rama main · réplica de lectura del repositorio original.
---
title: 'Tamery CLI'
sidebarTitle: 'Overview'
description: "Run the web app's queries on your own computer with tamery bridge: localhost, private networks, SQLite and DuckDB files, and connections whose password stays with you."
keywords:
['command line', 'terminal', 'tamery proxy', 'local proxy', 'headless']
---
`tamery bridge` lets the web app run your queries on the computer where the bridge runs. Use it for a database on localhost or a private network, a SQLite or DuckDB file, or a connection whose password Tamery's server doesn't have. The desktop app doesn't need it: it already runs queries on your computer.
## Install
On macOS and Linux:
```bash
curl -fsSL https://tamery.app/cli/install.sh | sh
```
On Windows, in PowerShell:
```powershell
irm https://tamery.app/cli/install.ps1 | iex
```
The script puts `tamery` in `~/.tamery/bin`, adds that folder to your `PATH`, and prints the command to run next. To install a specific version, set `TAMERY_VERSION`, for example `TAMERY_VERSION=1.2.0`.
If you have Node.js, npm works too, and so do pnpm and Bun:
```bash
npm i -g tamery
```
The CLI runs on macOS (Apple silicon and Intel), Linux (x64 and arm64), and Windows (x64 and arm64). It needs neither Node.js nor any other runtime. On Alpine and other musl-based Linux, install `libstdc++` first, for example `apk add libstdc++`.
## Run the bridge
1. Start the bridge:
```bash
tamery bridge
```
The first time, it opens the browser so you can sign in with the account you use in the web app. Then it opens **Settings → Bridge** in the web app.
2. Check that the **Bridge URL** is the one `tamery bridge` printed, usually `http://127.0.0.1:26380`, and click **Connect**.
3. **Settings → Bridge** and the terminal running `tamery bridge` both show a code. If they match, select **Yes** in the terminal and press **Enter**. **No** is selected first, and no answer within 2 minutes counts as no.
Keep the bridge running. The web app now sends every query through it, and a computer icon at the top of the window shows its state: a green dot while it answers, red within 10 seconds of it stopping. Hover it for the reason.
If the bridge stops, queries fail until you start it again. They never move to Tamery's cloud proxy on their own. To use the cloud proxy instead, for example while that computer is off, turn off **Run queries on** in **Settings → Bridge**. Turning it back on needs no new approval.
The bridge accepts only browsers signed in to the same account as the bridge.
## Paired browsers
An allowed browser stays allowed when the bridge restarts. To add another browser, click **Connect** there and allow it the same way.
A browser uses one bridge at a time. To switch to another bridge, click **Unpair** in **Settings → Bridge** first, or open the link the other bridge prints. **Unpair** and signing out also make the bridge forget this browser. To disconnect every browser at once, run [`tamery bridge unpair-all`](/cli/commands#tamery-bridge-unpair-all).
## Without a browser or terminal
On a server without a browser, open the sign-in link that `tamery bridge` prints on your own computer. Then enter the bridge's address as the **Bridge URL**. To reach it from another computer, see [Reach a bridge on another computer](/cli/remote).
When the bridge runs without a terminal to ask in, such as a service or a container, answer with [`tamery bridge approve`](/cli/commands#tamery-bridge-approve).
## Which connections it runs
The bridge runs only the connections saved in your account.
| Sync type | On the bridge |
| --- | --- |
| **Full** | Runs right away. |
| **No password** | Asks once for the password and the other secrets that don't sync. |
| **Metadata only** | Asks once for the server details. |
Some connections use this computer's files or credentials: a SQLite or DuckDB file, a certificate file (such as `sslkey` or `tlsCAFile`), an SSH tunnel, or a MongoDB login with the computer's AWS, OIDC or Kerberos credentials. The bridge runs them only once you allow them:
- **Saved in this browser:** already allowed.
- **Saved by someone else:** click **Allow** on **Allow this connection on the bridge**.
- **Edited since you allowed it,** in anything but the database name and secrets: allow it again. A teammate can't point the bridge at your files or credentials.
The first time a connection uses a file, tunnel or login, the terminal running `tamery bridge` also asks you to confirm.
To try a new connection while paired, save it first. Only saved connections run on the bridge.
SQLite and DuckDB paths, `~/` included, point to files on the bridge's computer. The first DuckDB file downloads DuckDB for the bridge, once. A DuckDB query through the bridge reads only its own file, never other files or URLs. SSH tunnels open there too, with its SSH keys, agent and `~/.ssh/config`. When an SSH host isn't in that computer's `known_hosts`, the bridge asks in its terminal whether to trust it. Without a terminal it refuses, so connect once with `ssh` there first.
The bridge reaches databases and files with the rights of the system user that runs it. On a shared server, run it as a user with no more access than it needs.
A query that runs longer than about 4 minutes fails.
## Manage connections
`tamery connection` creates, updates and deletes the connections in your account from the terminal. Changes show up in the app like changes made there. A connection you create with the CLI runs on the bridge on that computer without any more questions. A **Metadata only** one is the exception in the web app: each browser asks for its server details once, as for any **Metadata only** connection. [CLI commands](/cli/commands#tamery-connection-create) lists the flags.
In a script, without a terminal, `tamery connection` and `tamery query` never start signing in: they fail with **Not signed in** instead, so run `tamery login` on that computer first.
`tamery query` runs a statement on a connection from the terminal and prints the rows as a table, JSON or CSV. It only reads unless you pass `--write`, so it suits scripts and coding agents that run shell commands. See [tamery query](/cli/commands#tamery-query).
## Where secrets are stored
If this browser already has the secrets the bridge needs, it sends them on its own. Otherwise the web app opens the connection form on the missing fields. What you enter is saved in this browser and sent to the bridge once.
The bridge encrypts secrets with a key in the system keychain: the macOS Keychain, Windows Credential Manager, or the Secret Service on Linux. A Linux server often has no keychain. There the key goes into `~/.config/tamery/bridge.key`, readable only by your user, and the bridge warns on every start that file permissions are all that protect it. A computer you sign in to over SSH keeps the key in that file too, since a keychain prompt there would open on its own screen, where you can't answer it. Set `TAMERY_CONFIG_DIR` to keep these files somewhere other than `~/.config/tamery`.
If Tamery's servers can't be reached, connections the bridge ran since it started keep working, and so do connections whose details you entered or allowed on it. After a restart, other connections wait for the servers.
## Usage data
The CLI sends usage events to Tamery once you sign in, linked to your account, like the app does: signing in and out, starting the bridge and answering its questions, updates, and the `tamery connection` and `tamery query` commands. They carry the engine, the sync type, counts and whether a command worked, never names, connection strings, SQL or data. To turn them off, set `DO_NOT_TRACK=1`.
## Browser support
| Browser | Support |
| --- | --- |
| Chrome, Edge, Brave, Arc | Supported. The first **Connect** asks for permission to access devices on your local network. Allow it. |
| Firefox | Supported, with the same local network prompt. |
| Safari | Can't reach `http://127.0.0.1`. Use the desktop app, or give the bridge an [HTTPS address](/cli/remote). |
If you blocked the prompt, allow local network access for the web app in the browser's site settings and reload.
## Update
```bash
tamery update
```
Then restart the bridge. `tamery update` installs the latest version the same way you installed the CLI. [CLI commands](/cli/commands#tamery-update) covers what it does when something is in the way.
When it starts, `tamery bridge` checks for a newer version and tells you to run `tamery update` when there is one. **Settings → Bridge** shows the update too. When the web app needs a newer bridge, it stops sending queries to it and shows the update there.
<Cards>
<Card href="/cli/commands" />
<Card href="/cli/remote" />
</Cards>