# Getting started

## Install

Install the SDK in your project:

```bash
uv pip install omnictl
```

Install the CLI globally with `uv`:

```bash
uv tool install omnictl
```

Install the CLI directly from GitHub:

```bash
uv tool install git+https://github.com/SparkAIUR/omni-sdk.git
```

Upgrade a global install:

```bash
uv tool upgrade omnictl
```

For local development:

```bash
uv sync --extra dev
```

For local editable development:

```bash
uv pip install -e .
```

## Create config

`omnictl` resolves config with this precedence:

1. Runtime dict passed to `configure()` or client constructor.
2. Explicit `config_path=` argument.
3. `OMNI_SDK_CONFIG` environment variable.
4. Default search path (`~/.config/omnisdk/config.{yml|yaml|toml|json}` on Linux/macOS).

Example (`~/.config/omnisdk/config.yml`):

```yaml
version: 1
default_instance: prod
instances:
  prod:
    url: https://omni.example.com
    verify_tls: true
    auth:
      service_account_env_aliases:
        - OMNI_SERVICE_ACCOUNT_KEY
        - SIDERO_SERVICE_ACCOUNT_KEY
```

## First call (sync)

```python
from omni import OmniClient

client = OmniClient()
cluster = client.get_cluster("my-cluster")
print(cluster)
client.close()
```

## First call (async)

```python
from omni import AsyncOmniClient

async def main() -> None:
    client = AsyncOmniClient()
    cluster = await client.resources.get(
        {
            "namespace": "default",
            "type": "Clusters.omni.sidero.dev",
            "id": "my-cluster",
        }
    )
    print(cluster)
    await client.aclose()
```

## Unified client (sync + async)

```python
from omni import OmniClient

client = OmniClient()

# Sync
status = client.get_cluster_status("my-cluster")

# Async method on same instance
status_async = await client.aget_cluster_status("my-cluster")

await client.aclose()
```

## First CLI commands

```bash
omnipy config info
omnipy config contexts
omnipy get Clusters.omni.sidero.dev
omnipy cluster status my-cluster
omnipy kubeconfig --cluster my-cluster > my-cluster.kubeconfig
```

## Next step

See [Common Tasks](/common-tasks) for task-oriented CLI and SDK recipes aligned with common Omni workflows.
