deslicer-cli 1.0.0

Deslicer CLI — vendor-neutral CI client for planning, approving, and shipping Splunk changes via DAP.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# Environments

CI pipelines target a named **environment** (for example `production`, `staging`, `eu-prod`). The CLI resolves that name to a Deslicer tenant and Observer backend via deslicer-ai.

## File convention

Environment definitions live in the repository under:

```
.deslicer/environments/
├── production.yml
├── staging.yml
└── 550e8400-e29b-41d4-a716-446655440000.json
```

Supported extensions: **`.yml`**, **`.yaml`**, **`.json`**.

### Filename stem → environment name

The **filename stem** (without extension) is the environment name passed to `--environment`:

| File | `--environment` value |
|------|------------------------|
| `.deslicer/environments/production.yml` | `production` |
| `.deslicer/environments/staging.yaml` | `staging` |
| `.deslicer/environments/eu-prod.json` | `eu-prod` |

Example:

```bash
deslicer change plan --environment production
```

### UUID-named files (direct escape hatch)

When portal bindings are ambiguous (exit code **7**) or you need to pin an exact tenant without a friendly alias, name the file after the tenant UUID:

```
.deslicer/environments/550e8400-e29b-41d4-a716-446655440000.yml
```

Reference it directly:

```bash
deslicer auth login --environment 550e8400-e29b-41d4-a716-446655440000
```

UUID stems bypass fuzzy name matching and map one-to-one to the tenant record encoded in the file or resolved via the portal.

## File contents

Environment files carry metadata used by the Action layer and portal (Plan 1d). Typical fields:

```yaml
# .deslicer/environments/production.yml
tenant_code: acme-prod
description: Production Splunk fleet
target_group: plant-a
```

Exact schema validation is enforced by the composite Action and portal — the CLI consumes the resolved binding after OIDC auth, not by walking these files itself.

## Enumeration scope

**Important:** walking `.deslicer/environments/` to list available environments is performed by the **GitHub Action / composite Action layer** (Plan 1d — `deslicer/change-action`), not by the `deslicer` CLI binary.

The CLI accepts `--environment <name>` and validates the binding through deslicer-ai after authentication. It does not glob the directory locally.

For local discovery, list files manually:

```bash
ls .deslicer/environments/
```

## Portal bindings vs repo files

Two layers cooperate:

1. **Portal (deslicer-ai)** — maps `(repository, environment, OIDC subject)` → tenant + Observer URL. Required for CI OIDC.
2. **Repo files (`.deslicer/environments/*`)** — document and pin environment names for Actions/workflows; UUID stems disambiguate.

A missing portal binding causes exit code **6** even if a repo file exists. A missing repo file does not block the CLI when the portal binding is correct.

## Multi-environment repos

Monorepos may define many files:

```
.deslicer/environments/
├── production.yml
├── staging.yml
├── dev.yml
└── dr-failover.yml
```

Select per job:

```yaml
- run: deslicer change deploy --environment staging
- run: deslicer change deploy --environment production
  if: github.ref == 'refs/heads/main'
```

## Air-gapped override

When resolve-backend cannot reach deslicer-ai, operators may set `OBSERVER_API_URL` to talk to Observer directly. Environment files still name the logical target for workflows; the override is a break-glass path documented in [installation.md](installation.md).