# Command line interface The easiest way to execute Cypher queries against Memgraph is by using Memgraph's command-line tool, **mgconsole**. It is available as [Docker image](https://hub.docker.com/r/memgraph/mgconsole) and as a [binary](https://memgraph.com/download#individual) for macOS, and Windows. ## Install mgconsole To install or start `mgconsole` to query a running Memgraph database instance, use the following steps: **Docker šŸ³** You can use `mgconsole` on any OS from the Docker container. To connect to a remote Memgraph instance you need to provide the `--host` flag with the IP address or DNS name of the Memgraph instance and the `--port` flag with the port number, default `7687`. ```terminal docker run -it memgraph/mgconsole:latest [--host HOST] [--port PORT] ``` If you want to connect to your local Memgraph instance, you can use the following command on Linux host: ```terminal docker run -it memgraph/mgconsole:latest ``` If you are using MacOS or Windows, you can use the following command to start `mgconsole`: ```terminal docker run -it memgraph/mgconsole:latest --host host.docker.internal ``` On MacOS and Windows, `host.docker.internal` is a special DNS name that resolves to the host machine from a container. It is necessary to use it to connect to a Memgraph instance running on the host machine. **Windows** ### Download mgconsole Visit the [Download Hub](https://memgraph.com/download#individual) and download `mgconsole`. ### Start mgconsole From a terminal, start `mgconsole` with the command: ```terminal ./mgconsole --host HOST --port PORT ``` If Memgraph is running locally using the default configuration, start `mgconsole` with: ```terminal ./mgconsole --host 127.0.0.1 --port 7687 ``` **macOS** ### Download mgconsole Visit the [Download Hub](https://memgraph.com/download#individual) and download `mgconsole`. ### Provide execute permission From the terminal, provide the execution permission to the current user: ```terminal chmod u+x ./mgconsole ``` ### Start mgconsole Start mgconsole with the following command: ```terminal ./mgconsole --host HOST --port PORT ``` If Memgraph is running locally using the default configuration, start mgconsoleĀ with: ```terminal ./mgconsole --host 127.0.0.1 --port 7687 ``` **Linux** ### Build from source Follow the instructions on how to [build and install](https://github.com/memgraph/mgconsole#building-and-installing) mgconsole from source. ### Start mgconsole Start mgconsole with the following command: ```terminal mgconsole --host HOST --port PORT ``` If Memgraph is running locally using the default configuration, start mgconsoleĀ with: ```terminal mgconsole --host 127.0.0.1 --port 7687 ``` ## Execute Cypher queries After the client has started, it should present a command prompt similar to: ``` mgconsole X.X Connected to 'memgraph://127.0.0.1:7687' Type :help for shell usage Quit the shell by typing Ctrl-D(eof) or :quit memgraph> ``` At this point, it is possible to execute Cypher queries against a running Memgraph database instance. > **Note** > > You can use the `TAB` key to autocomplete commands in `mgconsole`. If you are new to Cypher, check out [how to query the database](https://memgraph.com/docs/querying). ### Query execution time Upon successful execution of a query, Memgraph will return the execution time. To get a breakdown of the execution time, set the `-verbose_execution_info` flag to `true`. It will extend the information about the execution time with the following data: ```bash Query COST estimate: 3066 Query PARSING time: 0.000175982 sec Query PLAN EXECUTION time: 0.0154524 sec Query PLANNING time: 8.054e-05 sec ``` The values show: - COST estimate - Internal planner estimation on the cost of the query. When comparing two query executions, an order of magnitude larger COST estimates might indicate the query's longer execution time. - PARSING time - Time spent checking if the query is valid and normalizing it for cache. - PLAN EXECUTION time - Time executing the plan. - PLANNING time - Time it takes the query planner to create the optimal plan to execute the query. ## Configure mgconsole Below are configurational flags you can use with mgconsole: ### Main | Flag | Description | Type | Default | |--------------------------|-------------------------------------------------------------------------------------------------------------------------|---------|---------| | -csv_delimiter | Character used to separate fields. | string | "," | | -csv_doublequote | Controls how instances of the quotechar(") appearing inside a field should themselves be quoted. When `true`, the character is doubled. When `false`, the escapechar is used as a prefix to the quotechar. If `csv_doublequote` is `false`, `csv_escapechar` must be set. | bool | true | | -csv_escapechar | Character used to escape the quote character (") if `csv_doublequote` is `false`. | string | "" | | -fit_to_screen | Fit output width to screen width. | bool | false | | -history | Use the specified directory to save history. | string | "~/.memgraph" | | -host | Server address. It can be a DNS resolvable hostname. | string | "127.0.0.1" | | -no_history | Do not save history. | bool | false | | -output_format | Query output format. Can be `csv`, `tabular` or `cypherl`. If the output format is not tabular `fit_to_screen` flag is ignored. `cypherl` can currently only be used with the DUMP DATABASE query. | string | "tabular" | | -password | Database password. | string | "" | | -port | Server port. | int32 | 7687 | | -term_colors | Use terminal colors syntax highlighting. | bool | false | | -use_ssl | Use SSL when connecting to the server. | bool | false | | -username | Database username. | string | "" | | -verbose_execution_info | Output the additional information about query such as query cost, parsing, planning and execution times. | bool | false | ### Flags | Flag | Description | Type | Default | |--------------------------|-------------------------------------------------------------------------------------------------------------------------|---------|---------| | -flagfile | Load flags from a file. | string | "" | | -fromenv | Set flags from the environment [example: 'export FLAGS_flag1=value']. | string | "" | | -tryfromenv | Set flags from the environment if present. | string | "" | | -undefok | Comma-separated list of flag names. These flags can be specified on the command line even if the program does not define a flag with that name. IMPORTANT: Flags from the list that have arguments MUST use the flag=value format. | string | "" | | -tab_completion_columns | The number of columns used in output for tab completion. | int32 | 80 | | -tab_completion_word | If non-empty, `HandleCommandLineCompletions()` will hijack the process and attempt to do bash-style command line flag completion on this value. | string | "" | ### Help | Flag | Description | Type | Default | |--------------------------|-------------------------------------------------------------------------------------------------------------------------|---------|---------| | -help | Show help on all flags [tip: all flags can have two dashes]. | bool | false | | -helpfull | Show help on all flags -- same as -help. | bool | false | | -helpmatch | Show help on modules, names of which contain the specified substring. | string | "" | | -helpon | Show help on the modules named by this flag value. | string | "" | | -helppackage | Show help on all modules in the main package. | bool | false | | -helpshort | Show help on the main module for this program only. | bool | false | | -helpxml | Produce an .xml version of help. | bool | false | | -version | Show version and build info then exit. | bool | false | ## Non-interactive mode **Docker šŸ³** If you want to use interactive mode with a `mgconsole` in a docker container, use the following command: ```bash echo "MATCH (n:Person) RETURN n;" | docker run -i memgraph/mgconsole:latest ``` To save the query results in a file, use the following command: ```bash echo "MATCH (n:Person) RETURN n;" | docker run -i memgraph/mgconsole:latest > results.txt ``` **Native installations** To get the query result in bash, use the following command: ```bash mgconsole < <(echo "MATCH (n:Person) RETURN n;") ``` or ```bash echo "MATCH (n:Person) RETURN n;" | mgconsole ``` To save the query results in a file, use the following command: ```bash mgconsole < <(echo "MATCH (n:Person) RETURN n;") > results.txt ```