# try
Lightweight, time‑sensitive directory navigation for experiments — a fast way to
jump between temporary project folders.
Inspired by and adapted from Tobias Lütke's original Ruby tool:
<https://github.com/tobi/try>
[](https://crates.io/crates/try-cli)
## Quick Start
**One-line install (Linux/macOS):**
```sh
Then restart your shell and run `try` to get started!
## Why `try`?
When experimenting you often create throwaway directories (e.g.,
`2025-08-21-test-feature-x`, `tmp-viz-poc`). Finding and jumping back to them
slows you down. `try` gives you an interactive, fuzzy selector that favors what
you touched most recently, and creates a new directory when your query doesn’t
exist — all wired to actually `cd` your shell.
## Features
- Interactive fuzzy finder: fast, incremental filtering of your tries.
- Time‑sensitive scoring: boosts recently created or visited dirs.
- Instant creation: press Enter to create when no exact match.
- Git clone integration: `try clone <url>` or pass a git URL to `try` to clone
into a date‑prefixed dir.
- One‑key deletion: Ctrl‑D, with an explicit “YES” confirmation.
- Shell integration: prints `cd` commands your shell evaluates.
- Native speed: single‑binary CLI written in Rust.
## Installation
### Recommended: Quick Install Script (Linux/macOS)
```sh
This script will:
- Detect your OS (Linux/macOS) and architecture (x86_64/aarch64/armv7)
- Download the latest pre-built binary from GitHub releases
- Extract and install it to `~/.local/bin`
- Check if `~/.local/bin` is in your PATH (warns if not)
- Automatically add shell integration to your rc file (bash/zsh/fish)
After installation, restart your shell or source your rc file to start using `try`.
To skip automatic shell integration:
```sh
For help:
```sh
### From Pre-built Binaries
Download the latest release for your platform from the [releases page](https://github.com/dariuszparys/try-rs/releases), extract it, and place the binary in your PATH.
### From crates.io
If you have Rust installed:
```sh
cargo install try-cli
```
Then enable shell integration and reload your shell:
```sh
eval "$(try init)"
source ~/.zshrc # or: source ~/.bashrc
```
### From Source
Prerequisites: a working Rust toolchain from <https://rustup.rs>
```sh
git clone https://github.com/dariuszparys/try-rs.git
cd try-rs
cargo install --path .
```
Or build a release binary: `cargo build --release` → `target/release/try`
If you installed from source instead of using `install.sh`, add shell integration manually:
```sh
eval "$(try init)"
source ~/.zshrc # or: source ~/.bashrc
```
## Shell Integration
If you used the install script, shell integration is already configured! Just restart your shell.
If you installed via another method, add the following to your shell configuration:
**bash/zsh:**
```sh
# add to ~/.bashrc or ~/.zshrc
eval "$(try init)"
```
**fish:**
```fish
# add to ~/.config/fish/config.fish
eval "$(try init | string collect)"
```
Then reload your shell:
```sh
source ~/.bashrc # or: source ~/.zshrc
```
Customize the storage location (default: `~/src/tries`) either by passing an
absolute path to `init` or by setting `TRY_PATH`. You can also override
per‑invocation with the global `--path` option:
```sh
eval "$(try init /absolute/path/to/tries)"
# or
export TRY_PATH=/absolute/path/to/tries
eval "$(try init)"
# or override at call time
try --path /absolute/path/to/tries
```
## Usage
Basic:
```sh
# With the shell function installed
try # Open the selector
try my-experiment # Seed the query (shell function calls `try cd ...`)
try https://github.com/user/repo # Shorthand for clone when integrated
# Direct binary usage without shell integration
try cd my-experiment
try clone https://github.com/user/repo.git
# Clone a git repo into a date-prefixed directory and cd into it
try clone https://github.com/user/repo.git
try clone git@github.com:user/repo my-fork # custom name
# Shorthand: passing a git URL to `try` behaves like `try clone`
# when the shell function is installed
try https://github.com/user/repo
```
Inside the selector:
- Up/Down or Ctrl‑P/Ctrl‑N: move selection
- Type: filter entries
- Enter: select existing or create `YYYY-MM-DD-<query>` and cd
- Ctrl‑D: delete the selected directory (requires typing `YES` to confirm)
- Esc/Ctrl‑C: cancel and return to the shell
Notes:
- If there’s no matching directory, Enter creates one (prefixed by
`YYYY-MM-DD-`) and jumps into it.
- Ranking combines fuzzy score with recency to surface likely targets.
- Query terms that start with a hyphen must be placed after `--` so they aren’t
parsed as flags, for example: `try cd -- --foo --bar`. With the shell function
installed, use: `try -- --foo`.
### Deletion semantics
- Ctrl‑D prompts for confirmation; type `YES` to permanently delete the selected
directory.
- File count and size are displayed before confirmation.
- Operations are restricted to the configured tries root; entries outside are
never touched.
## CLI Reference
- `try` (with no args): open the selector; with shell integration active, the wrapper evaluates the resulting shell commands for you.
- `try --help`: show top‑level help (lists subcommands and global options).
- `try init [--path PATH] [PATH]`: print the shell function; add it to your rc
file.
- `try cd [QUERY...] [--path PATH]`: launch selector and print the
`cd`/mkdir/touch commands (used by the shell function).
- `try clone <git-uri> [name] [--path PATH]`: print a clone pipeline (mkdir -p,
git clone, touch, cd) into the tries directory.
- Shorthand: `try <git-uri>` behaves like `try clone <git-uri>` when shell
integration is active.
- Subcommand help: `try cd --help`, `try init --help`, `try clone --help`.
## Configuration
- Default tries directory: `~/src/tries`
- Override via `TRY_PATH` env var or an absolute path argument to `try init`
## Troubleshooting
- `command not found: try`: ensure `~/.local/bin` (or `~/.cargo/bin` if installed via cargo) is on your `PATH` or reference
the binary directly, e.g. `eval "$(~/.local/bin/try init)"`.
- `try init` prints a shell function: expected. `init` emits shell code; evaluate
it with `eval "$(try init)"` (or add that line to your rc file) instead of
treating the printed function as normal command output.
- `try` prints something like `dir='...' && mkdir -p "$dir" && cd "$dir"` or
opens the selector but does not change directories: shell integration is not
active. Run `eval "$(try init)"`, then restart or reload your shell.
- `try my-experiment` or `try https://github.com/...` says `unrecognized subcommand`:
without shell integration, use `try cd my-experiment` or `try clone <git-uri>`
directly.
- Selector opens but no `cd` happens: confirm your rc file sources the `init`
function and that you restarted/reloaded the shell. If you have multiple shells configured, ensure the integration is in the correct shell's RC file (e.g., `~/.zshrc` for zsh, `~/.bashrc` or `~/.bash_profile` for bash).
- Wrong tries location: check `echo $TRY_PATH` or the path passed to `init`.
## Development
- Build: `cargo build` (or `cargo build --release`)
- Run: `cargo run -- [args]` (e.g., `cargo run -- cd foo`)
- Test: `cargo test --all --locked`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format: `cargo fmt --all`
Architecture: single‑binary CLI using `crossterm` for TUI, `dirs` for home
paths, and `unicode-width` for display width.
### Colors
- Help and error output from `clap` uses its built‑in color logic (color: auto)
and respects standard environment conventions.
- `try`’s own warnings and errors are styled on stderr when appropriate and
degrade to plain text when not:
- Colors enabled only if stderr is a TTY.
- `NO_COLOR` disables colors.
- `CLICOLOR=0` disables; `CLICOLOR_FORCE!=0` forces enable.
- When output is piped or redirected, styling is disabled to avoid ANSI
sequences in logs.
### Error Handling
- Internally, the app uses a small, typed error (`thiserror`) at high‑level
boundaries and returns plain `io::Error` for low‑level file operations.
- The selector and CLI keep a lenient UX: non‑critical issues print a warning
and continue; critical issues surface clearly and set a non‑zero exit where
appropriate.
## Security & Behavior
- `try` writes only under the configured tries directory (default
`~/src/tries`).
- No network access or secrets required.
## License
MIT — see [LICENSE](LICENSE).
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and PR expectations, and
[AGENTS.md](AGENTS.md) for structure, commands, style, and testing guidelines.