Metadata-Version: 2.4
Name: cd-browser
Version: 0.2.1
Summary: A fast keyboard-driven directory navigator for the terminal.
Author: Saky
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Dynamic: license-file

# cd-browser

**Stop typing paths. Browse them.**

`cd-browser` is a fast keyboard-driven directory navigator for the terminal.
It lets you explore directory trees visually and jump to any folder instantly.

![cd-browser demo](docs/demo.gif)

## Why cd-browser?

Working in the terminal often means:

- typing long directory paths
- navigating deep folder trees
- repeating `cd ..` multiple times

`cd-browser` provides an **interactive terminal UI** that allows you to browse directories with the keyboard and return the selected path directly to your shell.

## Features

- 🚀 Fast visual navigation of directory trees
- ⌨️ Fully keyboard-driven workflow
- 🌲 Expand and collapse directories
- 📜 Navigation history inside the session
- 🖥 Native terminal interface
- 🔁 Works with Bash, Zsh and other shells
- ⚡ Returns the selected path to the shell
- 🔎 Press `.` to toggle hidden directories

## Quick Demo

Run:

```bash
cd_
```

Browse directories using the arrow keys and press **Enter** to jump directly to the selected folder.

## Documentation

See the documentation index:

```
docs/index.md
```

## Installation

Install the project in user mode:

```bash
pip install cd-browser
```

**Important**: After installation, run this to set up the `cd_` command:

```bash
cd_browser_post_install
```

This interactive script will guide you through enabling `cd_` in your shell.

## Shell Integration For `cd_`

Because a Python subprocess cannot directly change the parent shell directory, use a shell wrapper that captures the final path printed by `cd_browser`.

Bash or Zsh example:

```bash
cd_() {
  local target
  target="$(cd_browser)" || return

  if [ -n "$target" ] && [ -d "$target" ]; then
    cd "$target"
  fi
}
```

After adding the function to your shell profile, reload it:

```bash
source ~/.bashrc
```

Or:

```bash
source ~/.zshrc
```

Then use:

```bash
cd_
```

- Dentro de `cd_browser`, presiona `.` para alternar la visualización de carpetas ocultas.

## Uninstall

If the project was installed with `pip`, remove it with:

```bash
pip uninstall cd-browser
```

**Important**: After uninstalling, remove the `cd_()` function from your shell profile (~/.bashrc or ~/.zshrc) to clean up completely.

## Developer Setup

Recommended setup:

```bash
make dev
```

Run the application in development mode:

```bash
python -m app.main
```

Useful development commands:

```bash
make fix
make quality
make run
```

## Template Origin

This project was created from the Python AI Dev Template.

The original template documentation has been preserved in `README_TEMPLATE.md` so the project-specific README can focus on `cd-browser` usage and development.

For the original template setup, conventions, and generic workflow notes, see `README_TEMPLATE.md`.
