Metadata-Version: 2.3
Name: uvrs
Version: 0.2.0
Summary: Create and run uv scripts with POSIX standardized shebang line
License: MIT License
         
         Copyright (c) 2025 Trey Hunner
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in
         all copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
         THE SOFTWARE.
Requires-Dist: click>=8.3.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# uvrs

This program is meant to be used in a shebang line, like this:

```python
#!/usr/bin/env uvrs
```

Unlike the shebang line [recommended by uv's documentation][uv shebang], the above shebang does not rely on the non-standard `-S` option (see [uv issue 11876][11876]).


## Installation

This should be installed as a globally available tool (so the above shebang line works):

```console
uv tool install uvrs
```


## Primary Usage

The primary purpose of the `uvrs` command is to accept a filename to be run as a uv script.

The `uvrs` command is not designed to run a script on its own.
If you need to run a script, use `uv run` for that.

The `uvrs` command can *also* be used to:

1. Create new uv scripts with a `uvrs` shebang line
2. Update existing uv scripts to use a `uvrs` shebang line


## Creating new uv scripts

To initialize a new uv script with a `uvrs` shebang line use the `init` command:

```console
uvrs init ~/bin/my-script --python 3.12
```

This will create the file `~/bin/my-script` using `uv init --script ~/bin/my-script --python 3.12` and then add an appropriate shebang line to the beginning of the script:

```python
#!/usr/bin/env uvrs
# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///


def main() -> None:
    print("Hello from my-script!")


if __name__ == "__main__":
    main()
```


## Updating existing uv scripts

To update an existing uv script to use the `uvrs` shebang, use the `fix` command:

```console
uvrs fix ~/bin/my-script
```

If the file does not yet have a shebang line, this shebang line will be added:

```python
#!/usr/bin/env uvrs
```

If the file being fixed already has a shebang line which uses `uv run`, the shebang will be updated to use `uvrs` instead.


## Managing dependencies

To update the dependencies within inline script metadata, use `uvrs add` and `uvrs remove`.

To add a new dependency:

```console
uvrs add ~/bin/my-script 'rich'
```

This is simply a shortcut for running `uv add --script ~/bin/my-script` 'rich'`.

To remove a new dependency:

```console
uvrs remove ~/bin/my-script 'rich'
```

This is simply a shortcut for running `uv remove --script ~/bin/my-script` 'rich'`.


## The goal

Eventually, I would like to see a similar tool [integrated into uv][16241].

Until that time, I plan to maintain this uvrs tool.


[uv shebang]: https://docs.astral.sh/uv/guides/scripts/#using-a-shebang-to-create-an-executable-file
[11876]: https://github.com/astral-sh/uv/issues/11876
[16241]: https://github.com/astral-sh/uv/issues/16241
