# How to use the q terminal (REPL)

_This page explains how to work in the q terminal: starting a session, evaluating expressions and suppressing their output, viewing and timing results, controlling how much the console prints, running system commands, recovering from an error, and exiting cleanly._

The q terminal — a read-eval-print loop, or REPL — is the primary interface to KDB-X. It is where you try an expression, look at data, time a query, and load a script. It is worth knowing well: you write most q by evaluating fragments at the prompt until they do the right thing, then moving them into a [script](../basics/use-scripts.md).

## Start a session
```bash
q
```

The banner reports the version, build date, and the environment q found:
```txt
KDB-X 5.0 2026.07.23 Copyright (C) 1993-2026 Kx Systems
l64/ 16(24)core 15644MB user machine 127.0.1.1 EXPIRE 2025.09.30 user@site.com COMMUNITY #12345678

Welcome to KDB-X Community Edition!
For Community support, please visit https://kx.com/slack
Tutorials can be found at https://github.com/KxSystems/tutorials
Ready to go beyond the Community Edition? Email preview@kx.com

q)
```

Naming a script runs it first, so a session can come up with your code already loaded — or do a job and exit:
```bash
$ cat hello.q
1 "hello world";
exit 0

$ q hello.q
hello world
```

See [how to develop scripts](../basics/use-scripts.md) for loading at startup versus at run time.

## Evaluate expressions

Press **Enter** and q evaluates the line and prints the result. Expressions evaluate **right to left**:
```q
q)sum 44.95 1032 107.15
1184.1
q)acos -1
3.141593
```

Assign with `:`, and the assignment itself prints nothing:
```q
q)pi:acos -1
q)pi
3.141593
```

[`show`](../../ref/show.md) both assigns and displays, which saves repeating the name:
```q
q)show pi:acos -1
3.141593
```

A trailing semicolon suppresses the result — useful when you want the effect but not a screenful of output:
```q
q)til 5
0 1 2 3 4
q)til 5;
q)
```

Semicolons also separate expressions on one line. Individual expressions evaluate right to left, but a sequence of them runs **left to right**:
```q
q)a:5;b:10;100*a+b
1500
```

so q assigns `a`, then `b`, then evaluates `100*a+b`.

> **Note — One line, one complete expression**
>
>
> The console evaluates each line on its own, so an expression cannot be continued onto a second line — both halves fail:
>
> ```q
> q)f:{[x]
> '{
>   [0]  f:{[x]
>             ^
> q)  x+1 }
> '}
>   [0]    x+1 }
>              ^
> ```
>
> Write it on one line, or put it in a [script](../basics/use-scripts.md#multiline-expressions), which allows continuation lines when they are indented and contiguous.
>
> Another option is a Jupyter notebook. In [q first mode](https://code.kx.com/pykx/examples/jupyter-integration.html#7-q-first-mode) of [KDB-X Python](../../get_started/kdb-x-python-overview.md), every notebook cell runs as q code by default, and a cell can span multiple lines. Enable it with:
>
> ```python
> import pykx as kx
> kx.util.jupyter_qfirst_enable()
> ```
>
> **Tip — Finding your way around the language**
>
>
> The [reference card](../../ref/index.md) lists every q keyword, operator, and utility on one page.
>
### k code

k is the predecessor of q: the same engine, terser syntax. The q keyword [`count`](../../ref/count.md) is `#` in k, and [`first`](../../ref/first.md) is `*`.

You can run k from a q session three ways — prefix a line with `k)`, switch interpreters with a lone `\`, or load a file with the `.k` extension via [`\l`](../../ref/syscmds.md#l-load-file-or-directory) or on the [command line](../../ref/cmdline.md#file):
```q
q)a:3 4 77 100 66 2
q)count a
6
q)k)#a
6
q)\
  #a
6
  \
q)
```

This matters mostly when reading legacy code; `\` on its own toggles back.

## View data

Enter a name to see its value:
```q
q)a:22
q)t:([]a:33 44;b:44 55)
q)v::a+33
q)t
a  b
-----
33 44
44 55
q)v
55
```

System commands list what a session holds — [`\v`](../../ref/syscmds.md#v-variables) for variables, [`\a`](./data_structures/tables.md) for tables, [`\b`](../../ref/syscmds.md#b-views) for views:
```q
q)\a
,`t
q)\b
,`v
q)\v
`s#`a`t`v
```

## Time an expression

Two system commands measure, and both belong in the REPL rather than in code.

[`\t`](../../ref/syscmds.md#t-timer) gives elapsed milliseconds, and takes an optional repeat count so a fast expression can be measured meaningfully:
```q
q)\t sum til 1000000
2
q)\t:100 sum til 10000
1
```

[`\ts`](../../ref/syscmds.md#ts-time-and-space) reports time and space — milliseconds and bytes:
```q
q)\ts sum til 1000000
2 8388880
```

The second figure is often the more interesting one when an expression is slower than expected.

## Control the display

q truncates large results, and a trailing `..` marks where. This is deliberate: printing a billion elements would cost far more than the query that produced them. The data is all still there — q cuts only the display.

[`\c`](../../ref/syscmds.md#c-console-size) sets the console size as rows and columns, and [`-c`](../../ref/cmdline.md#-c-console-size) does the same at startup:
```q
q)a:([]a:til 1000000;b:til 1000000)
q)\c 5 10000
q)a
a b
---
0 0
1 1
2 2
3 3
4 4
..
q)count a
1000000
```

[`\P`](../../ref/syscmds.md#p-precision) controls how many significant digits floats display with — worth remembering before concluding that two floats are equal, or that a value has been rounded.

## Pass options on the command line

You set session behavior with [command-line options](../../ref/cmdline.md), and you can combine several. Here q listens on port 5000 with the banner and prompt suppressed:
```bash
q -p 5000 -q
```

Your own options are available too: q keeps anything it does not recognize in [`.z.x`](../../ref/dotz.md#zx-argv), and [`.Q.opt`](../../ref/dotq.md#opt-command-parameters) parses them into a dictionary.
```bash
q -myparam 5432 -custom "data_processing_mode"
```
```q
q).Q.opt .z.x
myparam| "5432"
custom | "data_processing_mode"
```

Each value is a _list_ of strings even when there is only one, which the console display does not make obvious. See [handling command-line parameters](../basics/use-scripts.md#handle-command-line-parameters) for how to check that, and for defaults, type conversion, and positional arguments.

## Run system commands

[System commands](../../ref/syscmds.md) begin with a backslash:
```q
q)\P
7i
```

[`system`](../../ref/system.md) runs the same thing as a function, so the result can be captured:
```q
q)show p:system"P"
7i
```

[`\cd`](../../ref/syscmds.md#cd-change-directory) changes the working directory and `\pwd` reports it. Both matter because relative paths — to scripts and to databases — resolve against it:
```q
q)\pwd
"/home/me/proj"
```

q hands anything it does not recognize as a system command to the operating system:
```q
q)\ls -al ~/
"total 1560"
"drwxr-xr-x+  87 me    staff ..."
```

> **Warning — A mistyped system command runs as a shell command**
>
>
> That passthrough has no confirmation step. q does not reject a typo in a backslash command — the shell runs it, with whatever consequences follow. Be careful with commands entered in a hurry, especially in a production session.
>
### Comments

Everything after a `/` on a line is a comment. The `/` must be preceded by whitespace, or it reads as an operator:
```q
q)2+2 3 4   / add atom to vector
4 5 6
q)/ this whole line is a comment
```

Scripts support comment blocks as well — see [comments](../basics/use-scripts.md#comments).

## When something goes wrong

An expression that is not valid signals an error, with a caret under the primitive that failed:
```q
q)2+"a"
'type
  [0]  2+"a"
        ^
```

If the failure happens inside a function, q does not return the error — it suspends there and gives you a prompt inside the frame, indicated by the extra `)`. The function's arguments and locals are still in scope:
```q
q){x+2} "xyz"
'type
  [1]  {x+2}
           ^
q))x
"xyz"
```

`\` abandons the suspension and returns to the normal prompt:
```q
q))\
q)
```

That prompt is a complete debugger — you can walk the call stack, read the locals in each frame, and resume with a value. See [how to debug q code](../basics/debug.md).

### Interrupt a running expression

**Ctrl+C** stops a long-running or non-terminating expression, which q reports as `'stop`:
```q
q)while[1b]
'stop
  [0]  while[1b]
              ^
```

For a process serving other people, prefer a [query timeout](../interact_with_databases/hdb.md#query-timeout) to relying on somebody being at the keyboard.

## Exit the session

`\\` exits:
```q
q)\\
$
```

[`exit`](../../ref/exit.md) does the same from within code, and takes a return code — `exit 0` for success, which is how a script run as a batch job ends.

## Next steps

- Get line editing and command history with the [`kxline` embedded line editor](embedded-line-editor-kxline.md).
- Move what you have tried at the prompt into a [script](../basics/use-scripts.md).
- Learn the debugger properly in [how to debug q code](../basics/debug.md).
- Write functions: [how to work with functions](../basics/work-with-functions.md).
- Branch and iterate: [how to control execution](../basics/control-execution.md).
- Watch a session's footprint with [memory management](memory-management.md#memory-utilities).
