# Command Line

Open files, choose how they appear, or set text options when starting *Lx*.

## Basic use

Open one file:

```cli
lx notes.txt
```

Open several files:

```cli
lx notes.txt todo.md image.png
```

When you run `lx` from a Windows shell, it uses `lx.com`. This passes the command to `lx.exe` and makes `--wait` work correctly. Use `lx.exe` directly unless you need that behavior. Keep both files together.

A single startup file stays temporary until you edit or pin it. Selecting another file in the Browser can replace it.

Pin only the next file:

```cli
lx notes.txt --pin todo.md image.png
```

Here, only `todo.md` is pinned. Repeat `--pin` before each file you want to keep.

Open command-line help inside *Lx*:

```cli
lx --help
```

You can also use `-h`, `-?`, or `/?`.

Open a filename literally when it looks like an option or ends in location syntax:

```cli
lx --file report:10
lx --file --unusual-name
```

`--file` always consumes exactly the next argument as the filename.

Relative filenames are resolved from the terminal folder that launched the command, including when an existing Lx window receives the file.

## Choose how a file opens

Use these options for every file in the same command:

| Option | Shortcut | Opens as |
| --- | --- | --- |
| `--edit` | `-e` | Editable text |
| `--view` | `-v` | Read-only text |
| `--preview` | `-p` | A rendered preview, when available |
| `--bytes` | `-b` | Raw bytes |
| `--hex` | `-x` | Hexadecimal bytes |

Preview a Markdown file:

```cli
lx --preview readme.md
```

Open an image as raw hex:

```cli
lx --hex photo.jpg
```

The option may come before or after the file:

```cli
lx report.md --view
```

## Extract or unpack first

Some files hold other content. *Lx* can extract or unpack that content before showing it.

Extract readable text from an Office document:

```cli
lx --extract report.docx
```

Extract it and open the result as read-only text:

```cli
lx --extract --view report.docx
```

Extract it and inspect the result as hex:

```cli
lx --extract --hex report.docx
```

Extract it, treat the result as Markdown, and open it read-only:

```cli
lx --extract --format md --view report.docx
```

Unpack an Ableton Live Set and preview the resulting XML:

```cli
lx --unpack --preview song.als
```

| Option | Shortcut | Action |
| --- | --- | --- |
| `--extract` | `-ex` | Extract readable content |
| `--unpack` | `-un` | Unpack stored content |
| `--action NAME` | `-ac NAME` | Use a named action |
| `--handler NAME` | `-ha NAME` | Use a named file handler |
| `--source-format NAME` | `-sf NAME` | Set the format of the original file |

When extracting or unpacking, `--format` applies to the result. Use `--source-format` only when the original file needs a forced format.

An explicit edit, view, preview, bytes, or hex choice also applies to the result.

## Text settings

Open UTF-16 text:

```cli
lx --encoding utf16 notes.txt
```

Open text with a legacy codepage:

```cli
lx --codepage cp437 artwork.txt
```

Open a file with CRLF line endings and a tab size of 8:

```cli
lx --newline crlf --tab-size 8 source.txt
```

| Option | Shortcut | Meaning |
| --- | --- | --- |
| `--encoding NAME` | `-en NAME` | Select a UTF text encoding |
| `--codepage NAME` | `-cp NAME` | Select a legacy codepage |
| `--tab-size NUMBER` | `-t NUMBER` | Set the tab and indentation size |
| `--newline NAME` | `-nl NAME` | Use `lf`, `crlf`, or automatic line endings |
| `--defaults` | `-D` | Return to configured defaults |

Use `--codepage none` to clear a codepage choice without changing the main text encoding.

## New documents

Create an empty document:

```cli
lx --new
```

Create one with a name and Markdown format:

```cli
lx --name draft.md --format md --new
```

| Option | Shortcut | Meaning |
| --- | --- | --- |
| `--new` | `-n` | Create an empty document |
| `--name FILE` | `-N FILE` | Name the next new document |
| `--format NAME` | `-f NAME` | Set the final document format |

## Split files

Open two files side by side:

```cli
lx left.txt --pane-right right.txt
```

Use `--pane-left`, `--pane-right`, `--pane-up`, or `--pane-down` to choose the split direction.

## Reset options

Options continue to apply to later files in the same command. Use `--defaults` when later files should return to your configured defaults.

```cli
lx --view first.txt second.txt --defaults third.txt
```

## Open file locations

See [File References](file_references.md) for columns, ranges, multiple locations, offsets, counting options, and virtual paths.

Put a line, optional column, range, or absolute offset after the filename:

```cli
lx source.cpp:10
lx source.cpp:10:5
lx source.cpp:10:5-20:2
lx source.cpp:10-20,30,40-50
lx source.cpp:@100-200
```

Commas create multiple selections. Text ranges accept a column on either endpoint. Absolute offsets start with `@` and may be mixed with text locations.

Each resolved location adds a session bookmark at its starting line. Use *F2* and *Shift+F2* to move between them.

Locations can also come before the file:

```cli
lx +10:5 source.cpp
lx --line 10 --column 5 source.cpp
lx --goto 10:5-20:2,40 source.cpp
```

With one file, a prefix location may also follow the filename. With several files, put each location before its file. A location written in the filename wins over a prefix location.

| Option | Shortcut | Meaning |
| --- | --- | --- |
| `--line N` |  | Go to line `N` |
| `--column N` |  | Add a column to the current `--line` |
| `--goto LOCATION` | `+line[:column]` | Use the complete location syntax |
| `--wait` |  | Keep the launching process open until every requested document closes |

Lines and columns are one-based by default. Offsets are zero-based. Change those bases with:

| Option | Shortcuts |
| --- | --- |
| `--base=0` or `--base=1` | `-b0`, `-b1` |
| `--line-base=0` or `--line-base=1` | `-l0`, `-l1` |
| `--column-base=0` or `--column-base=1` | `-c0`, `-c1` |
| `--offset-base=0` or `--offset-base=1` | `-o0`, `-o1` |

A specific line, column, or offset base overrides `--base`. When the same setting appears more than once, the last value wins.

Choose how columns and offsets are counted:

| Option | Values | Default |
| --- | --- | --- |
| `--column-unit=UNIT` or `-cu UNIT` | `codepoint`, `utf8`, `utf16`, `byte` | `codepoint` |
| `--offset-unit=UNIT` | `byte`, `codepoint` | `byte` |
| `--range-end=MODE` | `inclusive`, `exclusive` | `inclusive` |

`byte` columns use the file's actual encoding. Byte offsets count from the start of the original file. Binary views accept byte offsets; decoded text locations and code-point offsets require a text document.

Use `--file PATH` when a filename ending in location-looking text must stay literal:

```cli
lx --file report:10
```

`--file --wait` opens a file literally named `--wait`; it does not enable waiting.
