# Configuration Guide

OWILIX uses YAML-based configuration stored at `~/.owi/owilix.cfg`. This guide covers configuration structure, migration, and CLI commands.

## Configuration Structure

```yaml
general:
  version: "4.0.0"
  server-update-url: "https://dashboard.ows.eu/api/owilix/default-cfg-4-0"
  license: "1.0"

server-config:
  version: "4.0"  # Config schema version
  last_update: "2026-01-05"

repositories:
  config:
    lexis:
      repository: lexis
      options:
        project_id: "proj862c5962623246664c1fda27b7afb108"
    local:
      repository: file
      options:
        path: ~/.owi/{access}
        collections_in_path: true
  selected_remote: [lexis]
  selected_local: [local]

profiles:
  default:
    showfields: "internalID,title,dataCenter,startDate,endDate,..."
    nodisplay: ".*"
    sort: "+startDate"

theme:
  info: "dim cyan"
  warning: "magenta"
  danger: "bold red"

user:
  name: "username"
  email: ""
  organisation: ""
```

---

## Configuration Commands

### View Configuration

```bash
# Show full config
owi config list

# Show specific keys (dot-notation)
owi config get repositories.config
owi config get server-config user.name

# Check version info
owi config version
```

### Use Local Config Only

By default, OWILIX merges in the latest server config on startup (remote repositories and defaults).
You can disable that behavior per command with `--no-remote-config`.

```bash
owi --no-remote-config remote ls all
owi --no-remote-config remote pull all/id=abc123
```

### Modify Configuration

```bash
# Set a value
owi config set user.email=user@example.com
owi config set repositories.config.local.options.path=/custom/path/{access}
```

### Add Repositories

```bash
# Add a LEXIS repository
owi config add-repo my-lexis -t lexis --project-id proj123

# Add a local file repository
owi config add-repo my-local -t file --path /data/owi/{access}

# Add an S3 repository
owi config add-repo my-s3 -t s3a \
  --endpoint https://s3.example.com \
  --path bucket/{access} \
  --key xxx --secret yyy
```

### Select Repositories

```bash
# Show current selection
owi config select --show

# Add repository to selection
owi config select --add my-s3

# Remove repository from selection
owi config select --remove old-repo

# Modify local selection
owi config select --type local --add my-local
```

### Migration

```bash
# Check if migration is needed
owi config version

# Preview migration changes
owi config migrate --dry-run

# Apply migration (creates backup)
owi config migrate
```

---

## Repository Types

| Type | Description |
|------|-------------|
| `lexis` | LEXIS platform via HTTP API (py4lexis 5.x) |
| `file` | Local filesystem storage |
| `s3a` | S3-compatible object storage |

### LEXIS Repository Options

```yaml
lexis:
  repository: lexis
  options:
    project_id: "proj862c5962623246664c1fda27b7afb108"
```

### Local File Repository Options

```yaml
local:
  repository: file
  options:
    path: ~/.owi/{access}
    collections_in_path: true
```

### S3 Repository Options

```yaml
my-s3:
  repository: s3a
  options:
    protocol: s3a
    endpoint: https://s3.example.com
    key: ${S3_KEY}      # can use env var expansion
    secret: ${S3_SECRET}
    path: bucket/{access}
    async: true
    anonymous: false    # set true for public buckets
```

---

## Configuration Migration

OWILIX tracks configuration versions via `server-config.version`. When upgrading:

1. **Backup**: Automatic backup at `~/.owi/owilix.cfg.bak`
2. **Sequential migrations**: V1→V2→V3→V4
3. **Preserves custom repos**: User-added repositories are not modified

### Migration History

| Version | Changes |
|---------|---------|
| V1 → V2 | Repository types `lexis` updated to `lexis+http` |
| V2 → V3 | Removed deprecated `it4i`, `lrz`, `lexishttp`; added unified `lexis` |
| V3 → V4 | Updated server URL to `default-cfg-4-0` |

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `OWS_OWI_PATH` | Base path for OWILIX data (default: `~/.owi`) |
| `PY4LEXIS_TOKEN` | Refresh token for authentication |
| `OWILIX_LEXIS_PROJECT_NAME` | Project name (default: `openwebsearch`) |
| `OWILIX_LEXIS_PROJECT_ID` | Project ID |
| `OWILIX_IRODS_CONNECTION_TIMEOUT` | iRODS timeout in seconds (default: 120) |

---

## Troubleshooting

### Reset to Defaults

```bash
# Delete config and restart with fresh defaults
rm ~/.owi/owilix.cfg
owi config version
```

### View Backup

```bash
cat ~/.owi/owilix.cfg.bak
```

### Disable Server Config Merging

```bash
owi config set general.server-update-url=""
```

Or in Python:

---


### Repository Management

Use `config add-repo` to easily add new repository definitions:
```bash
owi config add-repo my-s3 -t s3a --endpoint https://s3.example.com --key xxx --secret yyy
```

Use `config select` to manage active repositories (multi-selection supported):
```bash
# Add a repository to the active list
owi config select --add my-s3

# Remove a repository
owi config select --remove lexis

# Show current selection
owi config select --show
```

### Advanced Configuration

For complex nested configurations or inserting entire sections (like JSON trees), use `add-node`:

```bash
# Insert a complex dictionary at a specific key
owi config add-node repositories.config.custom_repo \
  "{\"repository\": \"s3a\", \"options\": {\"endpoint\": \"...\", \"bucket\": \"...\"}}" \
  --json
```


You can manipulate the configuration safely via the `OWIlixConfig` class (multi-key syntax supported):

```python
from owilix.core.manager import OWIlixConfig, OWIlixManager

# Point the manager to an alternative OWI path (where owilix.cfg lives)
mgr = OWIlixManager(owi_path="/srv/owi")
cfg = mgr.config  # type: OWIlixConfig

# 1) Change local repo path
cfg.add_config("repositories.config.local.options.path", "/data/owilix/{access}")
cfg.save_config()

# 2) Add a new S3 repo
cfg.add_config("repositories.config.backup-s3.repository", "s3a")
cfg.add_config("repositories.config.backup-s3.options.protocol", "s3a")
cfg.add_config("repositories.config.backup-s3.options.endpoint", "https://s3.backup.net")
cfg.add_config("repositories.config.backup-s3.options.path", "owi-archive/{access}")
cfg.add_config("repositories.config.backup-s3.options.async", True)

# 3) Activate it as a remote (append to list)
# Multi-key 'selected_remote#999' appends to list if index is out of bounds
cfg.add_config("repositories.selected_remote#999", "backup-s3")
cfg.save_config()

# 4) Load without remote server merge
cfg_no_remote = OWIlixConfig(cfg.config_file, no_remote=True)
```

### Selecting repositories at runtime

`OWIlixConfig.get_repositories` supports **additive** selection using `+`:

```python
# Use defaults + one extra
remotes, locals_ = cfg.get_repositories(remote=["+backup-s3"])

# Override defaults entirely (only these)
remotes, locals_ = cfg.get_repositories(remote=["backup-s3", "it4i"],
                                        local=["local"])
```