Metadata-Version: 2.4
Name: cx-command
Version: 0.1.0
Summary: AI-generated utility for firectory navigation by alias — jump to any directory with a short name
Project-URL: Homepage, https://github.com/armandino/cx-command
Project-URL: Issues, https://github.com/armandino/cx-command/issues
Author-email: Arman Sharif <armandino-gh@pm.me>
License-Expression: Apache-2.0
License-File: LICENSE.txt
Keywords: ai-generated,aliases,bookmark,cd,directory,navigation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Desktop Environment :: File Managers
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# cx — directory navigation by alias

**NOTE:** this project was generated by AI. Use at your own risk.

Jump to any directory with a short name. `cx` lets you define aliases for
commonly used directories and navigate to them instantly — with bash completion,
auto-assigned letter shortcuts, and sub-path navigation.

```bash
cx add src ~/projects/src
cx src                          # cd to ~/projects/src
c                               # cd by letter shortcut
cx src/sub/module               # cd with sub-path
cx -                            # cd to previous dir
```

## Install

```bash
pip install cx-command
```

Then add shell integration to your `~/.bashrc`:

```bash
eval "$(cx init bash)"
```

Restart your shell or `source ~/.bashrc`. That's it.

## Usage

| Command | Description |
|---------|-------------|
| `cx` | List all aliases (letter, name, path) |
| `cx <name>` | cd to alias |
| `cx <letter>` | cd by auto-assigned letter (a, b, c, ...) |
| `cx <name>/sub/path` | cd to alias joined with sub-path |
| `cx -` | cd to previous directory |
| `cx add <name> <path> [-g <group>]` | Add an alias |
| `cx rm <name>` | Remove an alias |
| `cx edit` | Open config in `$EDITOR` |
| `cx which <name>[/sub]` | Print resolved path (scriptable) |
| `cx recent [N]` | Show last N visited dirs |
| `cx open [<name>[/sub]] [-w <opener>]` | Open in file manager/VSCode/etc. |
| `cx ls <name>[/sub] [-- ls-args]` | List directory contents |
| `cx exec <name>[/sub] -- cmd args` | Run command in resolved dir |
| `cx init <shell>` | Print shell integration code |

## Config

Aliases are stored in `~/.cxrc.toml`. The file is created automatically on
first use.

```toml
[settings]
history_size = 50

[openers]
code = "code"
explorer = "explorer"

[aliases]
src = "${PROJECTS}/src"
nb  = "~/notebook"

[aliases.projects]
foo = "~/projects/foo"
bar  = "~/projects/bar"
```

- **Paths** support `${VAR}`, `$VAR` environment variable expansion and `~` home expansion.
- **Letters** (`a`, `b`, `c`, ... `aa`, `ab`, ...) are auto-assigned in the order aliases appear.
- **Groups** are for display only — all names are globally unique.
- **Openers** are named commands for `cx open`. The default opener is `xdg-open` on Linux, `open` on macOS, `explorer` on Cygwin/Windows.

### Scripting

`cx which` writes the resolved path to stdout without any shell directives, so
it's safe for subshell use:

```bash
cd "$(cx which foo)/conf"
cp "$(cx which foo)/config.yaml" .
```
