# CLI Reference
Complete command-line interface reference for bmrk.
## Synopsis
```
bmrk [OPTIONS] [PATH | BOOKMARK | BOOKMARK/SUBPATH]
bm [OPTIONS] [PATH | BOOKMARK | BOOKMARK/SUBPATH]
```
`bm` is the recommended shell wrapper (see [Installation](./installation.md)).
Use `bmrk` directly in scripts where `cd` behavior is not needed.
---
## Interactive Navigation
```bash
# Launch TUI from current directory
bm
# Launch TUI with a specific directory as root
bm /path/to/directory
# Launch TUI at a relative path
bm ../other-project
# Jump to a bookmark (no TUI — navigates instantly)
bm myproject
# Jump into a sub-directory of a bookmark (no TUI)
bm myproject/src/app
# Return to previous directory (wrapper only)
bm -
```
**Resolution order for positional argument**:
Without a path separator (e.g. `myproject`):
1. Saved bookmark with that name
2. Valid directory path (absolute or relative)
3. Error
With a path separator (e.g. `myproject/src/app`):
1. An existing relative path, resolved against the current directory
2. `BOOKMARK/SUBPATH` — the part before the first `/` is a saved bookmark and the
rest is resolved against that bookmark's directory (`..` is allowed; a trailing
`/` with no sub-path resolves to the bookmark itself)
3. Error
A leading `./` or `../` always forces plain path resolution and is never treated
as a `BOOKMARK/SUBPATH` reference.
---
## Bookmark Management
```bash
# List all saved bookmarks
bm -l
bm --list
# Add bookmark for the current directory
bm -a NAME
bm --add NAME
# Add bookmark for a specific path
bm -a NAME /path/to/directory
bm --add NAME /path/to/directory
# Remove a bookmark
bm -d NAME
bm --del NAME
```
**Bookmark naming rules**:
- No path separators (`/`, `\`) or null bytes
- No control characters
- Max 255 characters
- Cannot match a Windows reserved device name (`CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9`, `LPT1`-`LPT9`, case-insensitive)
- Otherwise permissive — letters, digits, hyphens, underscores, dots, and spaces are all allowed
(e.g. `.`, `..`, and `-` are valid bookmark names)
- Case-sensitive
---
## Help and Version
```bash
# Show help (all keys, config paths, CLI reference)
bm -h
bm --help
# Show version
bm -v
bm --version
```
---
## Options Reference
### `-h, --help`
Print the embedded help reference and exit. Covers all keybindings, CLI options,
configuration file location, and bookmark storage paths.
### `-v, --version`
Print version and build information, then exit: version, description, target platform
(OS/architecture), resolved config and bookmarks file paths, and the project homepage.
### `-l, --list`
List all saved bookmarks to stdout and exit.
### `-a, --add, -c NAME [PATH]`
Add a bookmark named `NAME`. If `PATH` is omitted, the current working directory is used.
### `-d, --del NAME`
Remove the bookmark named `NAME`.
### `[PATH|BOOKMARK]`
Optional positional argument.
- If a bookmark with this name exists — navigate to it (no TUI)
- If a valid directory path — open TUI rooted there
- Otherwise — error
---
## Storage
### Configuration
- **Linux/macOS**: `~/.config/bmrk/config.toml`
- **Windows**: `%APPDATA%\bmrk\config.toml`
Auto-created with defaults on first run.
### Bookmarks
- **Linux/macOS**: `~/.config/bmrk/bookmarks.json`
- **Windows**: `%APPDATA%\bmrk\bookmarks.json`
Auto-created when the first bookmark is added.
**Format** (JSON array):
```json
[
{ "key": "work", "path": "/home/user/work" },
{ "key": "webapp", "path": "/home/user/projects/webapp" }
]
```
---
## Exit Codes
| `0` | Normal exit |
| `1` | Error (invalid argument, path not found, etc.)|
---
## Environment Variables
### `BMRK_PREV_DIR`
Used by the `bm` wrapper to track the previous directory for `bm -`.
- **Set by**: the `bm` wrapper after each successful navigation
- **Format**: absolute directory path
- **Usage**: internal — do not set manually
---
## Script Integration
Use `bmrk` (not `bm`) in scripts to avoid the `cd` side-effect:
```bash
#!/bin/bash
# Capture selected path from bmrk
selected=$(bmrk /path/to/start)
if [ -d "$selected" ]; then
# Process selected directory
echo "Selected: $selected"
fi
```
---
## Examples
```bash
# Open TUI from current directory
bm
# Open TUI at /var/log
bm /var/log
# Jump to bookmark 'work' (no TUI)
bm work
# Jump to ~/projects/webapp/src via bookmark 'work' -> ~/projects/webapp
bm work/src
# Return to previous directory
bm -
# List all bookmarks
bm -l
# Create a bookmark for ~/projects/webapp
bm -a webapp ~/projects/webapp
# Remove a bookmark
bm -d webapp
# Show version
bm -v
# Show help
bm -h
```
---
## See Also
- [Getting Started](./getting-started.md)
- [Basic Usage](./usage.md)
- [Key Bindings](./keybindings.md)
- [Configuration](./configuration.md)
- [Installation](./installation.md)