# CLI

Source: https://athas.dev/docs/cli

Open files, viewers, terminals, and remote workspaces from the command line

Athas ships with a small CLI so you can jump into the right workspace or tool
without leaving your shell.

## Install the command

Install the `athas` command from **Settings > General > Terminal Command** inside the
app. Once installed, make sure the generated bin directory is in your `PATH`.

## Usage

```bash
athas [--new-window | --reuse-window] [paths...]
athas open [--new-window | --reuse-window] <paths...>
athas window
athas settings
athas extensions
athas pr <number> [--cwd <repository>]
athas issue <number> [--cwd <repository>]
athas action <run-id> [--cwd <repository>]
athas web <url>
athas terminal [--cwd <directory>] [--reuse-window] [--] [command...]
athas remote <connection-id> [name]
```

## Open files and folders

These commands open files or folders in Athas:

```bash
athas index.html
athas src/main.rs:120
athas .
athas open README.md docs/architecture.md
```

Athas automatically chooses the right surface for many file types:

- Images open in the image viewer
- PDF files open in the PDF viewer
- `.db`, `.sqlite`, `.sqlite3`, and `.duckdb` files open in the database viewer
- Markdown, HTML, and CSV files can be opened and then previewed inside Athas

## Open the web viewer

Use the built-in web viewer without opening the app first:

```bash
athas web https://athas.dev/docs
```

## Open a terminal tab

Open a blank terminal in the current working directory:

```bash
athas terminal
```

Open a terminal and run a command immediately:

```bash
athas terminal -- bun test
```

The terminal uses the directory where you ran the command as its working
directory.

## Open a remote workspace

If you already saved a remote connection in Athas, you can reopen it directly
from the shell:

```bash
athas remote conn-123
athas remote conn-123 "My Server"
```

Use the saved connection id from Athas' remote connections UI.

## Help

Print the built-in usage text:

```bash
athas --help
```

## Windows and standalone tools

Use `athas --new-window .` to open a project in a separate window, or `athas window` for an empty
window. `athas settings` and `athas extensions` open their corresponding surfaces. Repository
commands such as `athas pr 42 --cwd /path/to/repo` use the specified repository context.

Use `--reuse-window` when you want a supported target in the existing workspace. Put terminal
commands after `--` so their flags are passed to the command rather than the Athas launcher.

## Command not found

Install the command from Settings or **CLI: Install Terminal Command** in the command palette,
then open a new shell and check `athas --help`. Confirm the generated bin directory is on `PATH`.
The CLI opens existing paths: check the path and permissions if an open request fails.

See [Workspaces](https://athas.dev/docs/workspaces), [Remote connections](https://athas.dev/docs/remote), and [Browser](https://athas.dev/docs/browser).

## Related workflows

Use [Terminal](https://athas.dev/docs/terminal) to manage the opened session and [GitHub Integration](https://athas.dev/docs/github-integration) for repository account access.