Metadata-Version: 2.4
Name: urun-cli
Version: 0.4.0
Summary: End-user CLI for deploying apps to urun
Project-URL: Homepage, https://urun.sh
Project-URL: Repository, https://github.com/urun-sh/urun-cli
Project-URL: Issues, https://github.com/urun-sh/urun-cli/issues
Author: urun
License-Expression: MIT
License-File: LICENSE
Keywords: cli,deploy,urun
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# urun CLI

Deploy Python apps to urun from your terminal.

[![PyPI](https://img.shields.io/pypi/v/urun-cli.svg)](https://pypi.org/project/urun-cli/)
[![Python](https://img.shields.io/pypi/pyversions/urun-cli.svg)](https://pypi.org/project/urun-cli/)

## Install

```bash
uv tool install urun-cli
# or
pip install urun-cli
```

The package installs the `urun` command:

```bash
urun --version
```

For one-off `uvx` usage:

```bash
uvx --from urun-cli urun --version
# or the package-matching command alias
uvx urun-cli --version
```

## Quick start

Today, an operator manually vends an org-scoped deploy API key. Save it locally
with `urun login`:

```bash
urun login --api-key urun_<32hex>
```

`urun login` verifies the key with the urun API and stores credentials for later
commands. The future browser-based login flow is not available in this CLI
release.

For CI or one-off commands, you can still use the environment variable:

```bash
export URUN_API_KEY=urun_<32hex>
```

Create `app.py`:

```python
import urun
from urun import App

app = App("hello-h100")


@app.function(gpus="h100:1")
def hello(ctx: urun.Context):
    print(f"running on {ctx.device}")
    return {"device": str(ctx.device)}
```

Run it:

```bash
urun run app.py
```

In this release, `urun run` uses the same deploy pipeline as `urun deploy`.
`deploy` remains available as the lower-level command while the full
deploy/run/monitor workflow is being built.

## What gets deployed

`urun deploy` creates a source manifest from your Python entrypoint:

| Entrypoint | Included source |
| --- | --- |
| `urun deploy app.py` | `app.py` and local Python files it imports |

Dependencies are declared in your urun app code. Project-level files such as
`pyproject.toml` and `requirements.txt` are not uploaded as dependency
declarations by the CLI.

Generated/cache content such as `.git`, dotfiles, `__pycache__`, and `.pyc`
files is excluded. Add `.urunignore` to exclude additional paths.

Non-Python assets such as templates, static files, and data files are not
auto-included yet.

## Common options

Shared by `run` and `deploy`:

| Option | Description |
| --- | --- |
| `--name` | Override the derived app name. |
| `--api-url` | Override the API URL; defaults to `URUN_API_URL`, saved login credentials, or `https://api.urun.sh/v1`. |
| `--api-key` | Deploy API key; defaults to `URUN_API_KEY` or saved login credentials. |
| `--no-wait` | Finalize but do not poll for readiness. |
| `--poll-interval`, `--timeout` | Control readiness polling. |

## Troubleshooting

| Error | Fix |
| --- | --- |
| `missing API key` | Run `urun login`, set `URUN_API_KEY`, or pass `--api-key`. |
| `invalid API key format` | Use `urun_<32 lowercase hex chars>`. |
| `entrypoint not found` | Run from the project root or pass the entrypoint path. |
| `path is outside the project root` | Move the file under the project before deploying. |
| Expected files are missing | Import local Python files from `app.py`; non-Python assets are not auto-included yet. |

## Development

Contributing and test instructions are in [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT.

## Development environment

This repo has a Nix/direnv/devcontainer baseline:

```bash
direnv allow
just sync
just check
```

Use VS Code Dev Containers to open the repository with the same toolchain in a container. Copy `devcontainer.env.example` to `.devcontainer.env` if you need to pass local git identity or other non-secret development settings into the container.
