--- layout: default title: SQL and PPL CLI parent: SQL and PPL nav_order: 3 --- # SQL and PPL CLI The SQL and PPL command line interface (CLI) is a standalone Python application that you can launch with the `opensearchsql` command. To use the SQL and PPL CLI, install the SQL plugin on your OpenSearch instance, run the CLI using MacOS or Linux, and connect to any valid OpenSearch endpoint. ![SQL CLI]({{site.url}}{{site.baseurl}}/images/cli.gif) ## Features The SQL and PPL CLI has the following features: - Multi-line input - PPL support - Autocomplete for SQL syntax and index names - Syntax highlighting - Formatted output: - Tabular format - Field names with color - Enabled horizontal display (by default) and vertical display when output is too wide for your terminal, for better visualization - Pagination for large output - Works with or without security enabled - Supports loading configuration files - Supports all SQL plugin queries ## Install Launch your local OpenSearch instance and make sure you have the SQL plugin installed. 1. Install the CLI: ```console pip3 install opensearchsql ``` The SQL CLI only works with Python 3. {: .note } 2. To launch the CLI, run: ```console opensearchsql https://localhost:9200 --username admin --password admin ``` By default, the `opensearchsql` command connects to http://localhost:9200. ## Configure When you first launch the SQL CLI, a configuration file is automatically created at `~/.config/opensearchsql-cli/config` (for MacOS and Linux), the configuration is auto-loaded thereafter. You can configure the following connection properties: - `endpoint`: You do not need to specify an option. Anything that follows the launch command `opensearchsql` is considered as the endpoint. If you do not provide an endpoint, by default, the SQL CLI connects to http://localhost:9200. - `-u/-w`: Supports username and password for HTTP basic authentication, such as with the security plugin or fine-grained access control for Amazon OpenSearch Service. - `--aws-auth`: Turns on AWS sigV4 authentication to connect to an Amazon OpenSearch endpoint. Use with the AWS CLI (`aws configure`) to retrieve the local AWS configuration to authenticate and connect. For a list of all available configurations, see [clirc](https://github.com/opensearch-project/sql/blob/main/sql-cli/src/opensearch_sql_cli/conf/clirc). ## Using the CLI 1. Run the CLI tool. If your cluster runs with the default security settings, use the following command: ```console opensearchsql --username admin --password admin https://localhost:9200 ``` If your cluster runs without security, run: ```console opensearchsql ``` 2. Run a sample SQL command: ```sql SELECT * FROM accounts; ``` By default, you see a maximum output of 200 rows. To show more results, add a `LIMIT` clause with the desired value. To exit the CLI tool, select **Ctrl+D**. {: .tip } ## Using the CLI with PPL 1. Run the CLI by specifying the query language: ```console opensearchsql -l ppl ``` 2. Execute a PPL query: ```sql source=accounts | fields firstname, lastname ``` ## Query options Run a single query with the following command line options: - `-q`: Follow by a single query - `-f`: Specify JDBC or raw format output - `-v`: Display data vertically - `-e`: Translate SQL to DSL ## CLI options - `--help`: Help page for options - `-l`: Query language option. Available options are `sql` and `ppl`. Default is `sql` - `-p`: Always use pager to display output - `--clirc`: Provide path for the configuration file