# gqueue Reference
`gqueue` lists jobs in the scheduler with filtering, formatting, and tree/group views.
## Usage
```bash
gqueue [options]
gqueue completion <shell>
```
## Common Examples
```bash
gqueue # active jobs (Queued, Hold, Running)
gqueue -a # all jobs including completed
gqueue -s Running,Queued # filter by state
gqueue -j 12,13,14 # filter by job IDs (comma-separated)
gqueue -u alice # filter by user (default: current user; use 'all' for all users)
gqueue -P ml-research # filter by project code
gqueue -T # only jobs with active tmux sessions
gqueue -t # dependency tree view
gqueue -g # group by state
gqueue -w # auto-refresh every 2s
gqueue -w --interval 5 # auto-refresh every 5s
```
## Output Format
Default format:
```text
JOBID,NAME,ST,TIME,NODES,NODELIST(REASON)
```
Custom format:
```bash
gqueue -f JOBID,NAME,PROJECT,ST,TIMELIMIT,MEMORY,NODELIST(REASON)
```
Supported fields for `-f/--format`:
- `JOBID`
- `NAME`
- `ST`
- `TIME`
- `TIMELIMIT`
- `MEMORY`
- `NODES` (GPUs requested)
- `NODELIST(REASON)` (running: GPU indices; queued/hold/cancelled: reason)
- `USER`
- `PROJECT`
Example `gqueue -t` output:
```
JOBID NAME ST TIME NODES NODELIST(REASON)
1 prep CD 00:02:15 0 -
├─2 train R 00:10:03 1 0
└─3 eval PD - 0 (WaitingForDependency)
```
## Options
- `-n, --limit <N>`: show first/last N jobs (positive: first N, negative: last N, `0`: all; default: `0`)
- `-a, --all`: show all jobs including completed
- `-c, --completed`: show only completed jobs
- `--since <when>`: show jobs since `1h`, `2d`, `3w`, `today`, `yesterday`, or a timestamp
- `-r, --sort <field>`: `id`, `state`, `time`, `name`, `gpus`, `priority`
- `-s, --states <list>`: comma-separated states (e.g. `Queued,Running`)
- `-u, --user <list>`: comma-separated users (default: current user; use `all` for all users; alias: `--users`)
- `-j, --jobs <list>`: comma-separated job IDs (e.g. `1,2,3`; alias: `--job`)
- `-N, --names <list>`: comma-separated job names
- `-P, --project <code>`: filter by project code
- `-f, --format <fields>`: comma-separated output fields
- `-g, --group`: group by state
- `-t, --tree`: tree view (dependencies + redo links)
- `-T, --tmux`: only jobs with active tmux sessions
- `-w, --watch`: auto-refresh job list (default: every 2s)
- `--interval <N>`: refresh interval in seconds for `--watch` (default: `2`)