---
title: "The GSQL Shell"
description: "Overview of the GSQL shell."
component: "tigergraph-server"
version: "4.3"
module: "gsql-shell"
html_url: "/tigergraph-server/4.3/gsql-shell/"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/index.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/)

# The GSQL Shell

The GSQL shell is a fully functional Java environment for interacting with the TigerGraph database. It is one of the primary ways to interact with the TigerGraph database and is included in a standard TigerGraph installation.

To learn more about the GSQL language, follow our tutorial series starting with [GSQL V3 Tutorial](https://github.com/tigergraph/ecosys/blob/master/demos/guru%5Fscripts/docker/tutorial/4.x/README.md).

## Launch the shell

As the TigerGraph Linux user, type `gsql` into the bash terminal to start a GSQL shell session:

```console
$ gsql
```

If authentication is enabled, you will need to provide credentials in order to launch the shell.

## Change scope

In the GSQL shell, you can run commands on a global scope or on a local scope. When you start a GSQL session, you are in the global scope. To change to the local scope of a graph, run the `USE GRAPH` command.

```GSQL
GSQL > USE GRAPH social
Using graph 'social'
```

To switch back to the global scope, run `USE GLOBAL`.

```GSQL
GSQL > USE GLOBAL
```

Operating on different scopes will require different privileges. For more information, see Roles and Privileges.

## Multi-line commands

By default, GSQL treats each line as one command; the GSQL interpreter will activate as soon as the end-df-line character is entered.

```gsql
GSQL > ls (1)
---- Global vertices, edges, and all graphs
Vertex Types:
  - VERTEX Person(PRIMARY_ID id STRING, name STRING, score FLOAT, tag STRING, flag BOOL) WITH STATS="OUTDEGREE_BY_EDGETYPE"
  - DIRECTED EDGE Friend(FROM Person, TO Person, weight FLOAT, tag STRING, flag BOOL) WITH REVERSE_EDGE="Also_Friend"
  - DIRECTED EDGE Also_Friend(FROM Person, TO Person, weight FLOAT, tag STRING, flag BOOL) WITH REVERSE_EDGE="Friend"
  - UNDIRECTED EDGE Coworker(FROM Person, TO Person, weight FLOAT, tag STRING, flag BOOL)

Graphs:
  - Graph social(Person:v, Friend:e, Also_Friend:e, Coworker:e)
Jobs:


JSON API version: v2
Syntax version: v1
GSQL > CREATE QUERY example () { (2)
Encountered "<EOF>" at line 1, column 25.
Was expecting:
    "}" ...
```

| **1** | GSQL executes a single-line command immediately after encountering the end-of-line character. |
| --- | --- |
| **2** | Trying to enter a multi-line command in the default single-line mode will cause an error. |

Multi-line mode allows the user to enter several lines of text without triggering immediate execution. This is useful when a statement is very long and the user would like to split it into multiple lines. It is also useful when defining a job or query, because they typically contain multiple statements.

To enter multi-line mode, use the command `BEGIN`. The end-of-line character is now disabled from triggering execution. The shell remains in multi-line mode until the command `END` or `ABORT` is entered. The `END` command triggers the execution of the multi-line block. Alternately, the `ABORT` command exits multi-line mode and discards the multi-line block.

### Example

In the example below, `BEGIN` and `END` are used to allow the SELECT statement to be split into several lines:

```gsql
GSQL > BEGIN
GSQL > CREATE QUERY example () {
GSQL > PRINT "Hello world";
GSQL > }
GSQL > END
Successfully created queries: [example].
```

## Run GSQL scripts and in-line commands

You don't always need to enter the interactive shell in order to run a GSQL command. You can also run command in-line or through a GSQL script.

To run a GSQL command non-interactively, run the bash command `gsql` followed by the GSQL commands you want to run in quotes:

```console
$ gsql 'ls'
```

To run a GSQL script, put all your GSQL commands in a file (conventionally ending with the extension .gsql), and run:

```console
$ gsql <filename>
```

Replace `<filename>` with the name of the script file.

You can also run a GSQL script from the GSQL shell. To do so, type in the file name prefixed with the `@` character:

```gsql
GSQL > @<filename>
```

Replace `<filename>` with the name of the script file.
