---
name: azion-install-the-edgesql-shell
description: >-
  Clone the EdgeSQL Shell from its repository, install its dependencies in a virtual environment, and authenticate it with your personal token.
---

# Install the EdgeSQL Shell

EdgeSQL Shell is a Python command-line tool that manages [SQL Database](/en/documentation/platform/sql-database/) databases, runs SQL against them, and imports data into them. It is not published on a package index: you clone [the repository](https://github.com/aziontech/edgesql-shell) and install it from source. The shell authenticates with your personal token, read from the `AZION_TOKEN` environment variable.

For the commands the shell accepts once it is installed, refer to [EdgeSQL Shell](/en/documentation/platform/sql-database/edgesql-shell/).

> **Caution**
>
> EdgeSQL Shell does not start on a clean install. Every command fails before the `EdgeSQL>` prompt appears, with `ImportError: cannot import name 'Configuration' from 'kaggle.api.kaggle_api_extended'`: `commands/import.py` imports the Kaggle module unconditionally while the shell starts, and the pinned `kaggle==1.8.3` no longer defines that symbol. Downgrading does not rescue it on a machine with no Kaggle credentials, because the package authenticates inside its own `__init__.py` — `1.6.17` and `1.7.4` fail there instead. A fix is pending.
>
> Stubbing that one import out locally leaves the rest of the tool working. It is a local workaround, not a supported step. For the interfaces that run the same SQL until the fix ships, refer to [Troubleshooting](/en/documentation/platform/sql-database/troubleshooting/).

---

## Prerequisites

- Python 3, with the `venv` module it ships with.
- The Postgres headers. `requirements.txt` pins `psycopg2`, which builds from source and fails to compile without them. On macOS, install them with `brew install postgresql`.
- A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/). The shell reads it from `AZION_TOKEN`.
- SQL Database enabled on your account. The product is in Preview and is not enabled by default, so request access through [Technical Support](/en/documentation/support/).

---

## Install the shell

The install clones the repository, isolates the dependencies in a virtual environment, and puts the token in the environment the shell reads. To install the shell:

1. **Clone the repository**

   ```bash
   git clone https://github.com/aziontech/edgesql-shell.git
   ```

   Git writes the tool into an `edgesql-shell` directory under the current one.

2. **Enter the directory**

   ```bash
   cd edgesql-shell
   ```

3. **Create and activate a virtual environment**

   ```bash
   python -m venv env
   source env/bin/activate
   ```

   The `env` directory holds the environment, and it stays active for the rest of the terminal session.

4. **Install the dependencies**

   ```bash
   pip install -r requirements.txt
   ```

   The packages land in `env` rather than in the system Python. `psycopg2` compiles here, against the Postgres headers from the prerequisites.

5. **Export your personal token**

   ```bash
   export AZION_TOKEN="[TOKEN VALUE]"
   ```

   Replace `[TOKEN VALUE]` with your personal token. The variable holds for the current terminal session.

6. **Start the shell**

   ```bash
   python edgesql-shell.py
   ```

   On a clean install, the startup ends in the import failure instead of the prompt:

   ```text
   ImportError: cannot import name 'Configuration' from 'kaggle.api.kaggle_api_extended'
   ```

The tool is installed in `edgesql-shell`, with its dependencies in the `env` environment and your token in `AZION_TOKEN`. The shell opens on the `EdgeSQL>` prompt, where each line you enter is a shell command or a SQL statement against the database in use.

Until the defect above is fixed, the last step ends on the `ImportError` rather than on the prompt. The installation itself is complete: the repository, the environment, the dependencies, and the token are all in place, and the shell starts once the Kaggle import is repaired upstream.

---

## Run a command without the interactive prompt

Two flags run the shell without the prompt. `-n` makes the run non-interactive, and `-c` passes one command. Repeat `-c` to run several commands in order:

```bash
python edgesql-shell.py -n -c ".use MyDB" -c ".tables"
```

The run selects the `MyDB` database, lists its tables, and exits. It reaches the `ImportError` too until the fix ships, because the shell loads the same modules whichever way it starts.

---

## Next steps

- [EdgeSQL Shell](/en/documentation/platform/sql-database/edgesql-shell.md): Every command the shell accepts, its arguments, the output modes, and the credential variables.
- [Import data with the EdgeSQL Shell](/en/documentation/guides/application-development/data/import-data-sql-database.md): Load a CSV file, a SQL script, or another database into a table from the shell.
- [Create and manage databases](/en/documentation/guides/application-development/data/manage-sql-database.md): Create a database from Azion Console, the Azion API, or the azion library, then list and delete it.
- [Troubleshooting](/en/documentation/platform/sql-database/troubleshooting.md): The symptoms SQL Database and its shell return, and what each one means.