# DuckDB CLI > Learn to connect and query databases using MotherDuck from the DuckDB CLI MotherDuck has two command-line tools, and they do different jobs: | Tool | Use it to | |---|---| | **DuckDB CLI** (`duckdb`), this page | Run SQL interactively over local files and MotherDuck databases in one session | | **[MotherDuck CLI](./motherduck-cli/index.md)** (`motherduck`) | Sign in or create an account, script queries with JSON output, and build and publish [Dives](/key-tasks/dives/) and [Flights](/key-tasks/flights/) | The install script below installs both, so you can pick one per task. ## Installation :::note MotherDuck supports DuckDB client versions 1.4.1 through 1.5.5 in all regions. For the range each region supports, see [client version support](/about-motherduck/cloud-regions/#client-version-support). ::: The MotherDuck install script downloads a MotherDuck-supported DuckDB version, installs the `motherduck` extension, installs the MotherDuck CLI under `~/.motherduck/`, and offers to fetch and persist a MotherDuck token. To install the DuckDB CLI on its own, set `SKIP_MOTHERDUCK_CLI=1`. ### Windows The recommended way to install both CLIs is with the MotherDuck install script: ### Install with PowerShell ```powershell powershell -c "irm https://install.motherduck.com | iex" ``` DuckDB lands in `%LOCALAPPDATA%\duckdb\cli`. If your PowerShell execution policy blocks the command above, use the `cmd.exe` fallback: ```bat curl -sfL -o install.bat https://install.motherduck.com/install.bat && install.bat ``` The `cmd.exe` script installs the `windows-amd64` DuckDB build only. It cannot install the MotherDuck CLI or run the interactive token flow. On ARM64, or for either of those, use the PowerShell script. ### Download the binary To install manually instead: 1. Download the 64-bit Windows binary [duckdb_cli-windows-amd64.zip](https://github.com/duckdb/duckdb/releases/download/v1.5.5/duckdb_cli-windows-amd64.zip) 2. Extract the zip file. ### macOS The recommended way to install both CLIs is with the MotherDuck install script: ### Install with bash ```bash curl -s https://install.motherduck.com | sh ``` ### Linux The recommended way to install both CLIs is with the MotherDuck install script: ### Install with sh ```bash curl -s https://install.motherduck.com | sh ``` The script detects your architecture and installs the matching `linux-amd64` or `linux-arm64` DuckDB binary. The MotherDuck CLI needs glibc, and the script installs it first, so on a musl-based distribution such as Alpine the script stops with an error before it reaches DuckDB. Set `SKIP_MOTHERDUCK_CLI=1` to install the DuckDB CLI there. ### Download the binary To install manually instead: 1. Download the Linux binary: - For 64-bit, download the binary [duckdb_cli-linux-amd64.zip](https://github.com/duckdb/duckdb/releases/download/v1.5.5/duckdb_cli-linux-amd64.zip) - For arm64/aarch64, download the binary [duckdb_cli-linux-aarch64.zip](https://github.com/duckdb/duckdb/releases/download/v1.5.5/duckdb_cli-linux-aarch64.zip) 2. Extract the zip file. For more information, see the [DuckDB installation documentation](https://duckdb.org/docs/installation/). ## Try it Walk through starting DuckDB, attaching MotherDuck, and running your first query in the playground below. Each step explains what happens before you press Enter, so you can preview the full flow before running it on your machine. Interactive CLI demo omitted from generated Markdown. Static walkthrough: ```bash duckdb ATTACH 'md:'; SHOW DATABASES; FROM duckdb_tables() WHERE database_name = 'sample_data'; ``` ## Step by step ### Start the DuckDB CLI After installing, start DuckDB from your terminal: ```sh duckdb ``` DuckDB opens an in-memory database by default, so any tables you create won't persist when you exit. Pass a filename to open or create a persistent local database: ```sh duckdb mydatabase.duckdb ``` ### Connect to MotherDuck From inside the DuckDB CLI, attach MotherDuck: ```sql ATTACH 'md:'; ``` DuckDB downloads the signed MotherDuck extension and opens your default browser to authenticate. Follow the instructions in the terminal. To list your MotherDuck databases and confirm the connection, run: ```sql SHOW DATABASES; ``` You can query local DuckDB data and MotherDuck databases from the same session. For more on persisting your authentication credentials, see [Authenticating to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md). :::tip You can also connect to MotherDuck directly when starting DuckDB: ```bash duckdb "md:" ``` ::: :::note[Manual extension update] When MotherDuck releases a new extension version you can force-reinstall the extension from the CLI. ```sh FORCE INSTALL motherduck; ``` ::: ### Connect without a MotherDuck account `ATTACH 'md:'` signs in to an account you already have. Where there isn't one, create it from the terminal instead of filling in a signup form. Both routes below call the same signup endpoint, but the two CLIs keep separate credentials, so pick the one for the tool you want to work in. To work in the MotherDuck CLI, [`motherduck new`](/sql-reference/motherduck-cli/new/) creates the account and saves the token, so the query that follows is already authenticated: ```bash motherduck new motherduck query "SELECT count(*) FROM sample_data.nyc.taxi" ``` To work in the DuckDB CLI, put the token in the environment. `POST https://new.motherduck.com` is the endpoint `motherduck new` wraps, and it hands the token back as a value you can export: ```bash ACCOUNT=$(curl -s -X POST https://new.motherduck.com) export motherduck_token=$(echo "$ACCOUNT" | jq -r .motherduck_token) duckdb "md:" -c "SELECT count(*) FROM sample_data.nyc.taxi" ``` :::note Installing the MotherDuck CLI doesn't authenticate the DuckDB CLI. `motherduck new` and `motherduck login` write to `~/.motherduck/credentials.json`, which the `motherduck` extension doesn't read, so a later `ATTACH 'md:'` opens the browser and signs in to whichever account you already have. `motherduck_token` is what the DuckDB CLI reads. ::: Either route gives you a Free Plan organization with a default database named `my_db`, and `sample_data` attached to query straight away. `motherduck new --region` picks the region. :::warning The organization has no owner, and it lapses 72 hours after it's created along with everything in it. Open the claim URL to take ownership and keep your work: ```bash motherduck new claim # or, from the raw response: echo "$ACCOUNT" | jq -r .claim_org_url ``` ::: This is the path to take when a script or an AI agent has a shell but no credentials. See [create and claim accounts for AI agents](/key-tasks/ai-and-motherduck/agent-account-signup.md) for the rest of the response, and [working with agents](./motherduck-cli/agents.md) for what an agent can build from there. ### Open the MotherDuck UI from the CLI Launch the MotherDuck UI from your terminal: ```bash duckdb -ui ``` If you're already in a DuckDB session, run `CALL start_ui();` instead. ## Next steps - [MotherDuck CLI](./motherduck-cli/index.md) for scripting MotherDuck, and for building Dives and Flights from the terminal - [Authenticating to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md) for tokens, read scaling, and attach modes - [Loading data into MotherDuck](/key-tasks/loading-data-into-motherduck/) once you have somewhere to put it --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fgetting-started%2Finterfaces%2Fconnect-query-from-duckdb-cli%2F&page_title=Install%20and%20connect%20with%20the%20DuckDB%20CLI&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.