previty-cli 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- previty_cli/AGENTS.md +78 -0
- previty_cli/__init__.py +3 -0
- previty_cli/__main__.py +4 -0
- previty_cli/api/__init__.py +0 -0
- previty_cli/api/client.py +381 -0
- previty_cli/api/models.py +659 -0
- previty_cli/app.py +156 -0
- previty_cli/clock.py +13 -0
- previty_cli/commands/__init__.py +0 -0
- previty_cli/commands/_common.py +117 -0
- previty_cli/commands/agents.py +25 -0
- previty_cli/commands/apps.py +26 -0
- previty_cli/commands/auth.py +101 -0
- previty_cli/commands/checks.py +320 -0
- previty_cli/commands/readiness.py +27 -0
- previty_cli/commands/results.py +77 -0
- previty_cli/commands/sources.py +94 -0
- previty_cli/config.py +200 -0
- previty_cli/errors.py +126 -0
- previty_cli/exit_codes.py +31 -0
- previty_cli/output/__init__.py +44 -0
- previty_cli/output/json.py +24 -0
- previty_cli/output/markdown.py +70 -0
- previty_cli/output/table.py +256 -0
- previty_cli/py.typed +0 -0
- previty_cli/redact.py +34 -0
- previty_cli-0.1.0.dist-info/METADATA +182 -0
- previty_cli-0.1.0.dist-info/RECORD +31 -0
- previty_cli-0.1.0.dist-info/WHEEL +4 -0
- previty_cli-0.1.0.dist-info/entry_points.txt +2 -0
- previty_cli-0.1.0.dist-info/licenses/LICENSE +10 -0
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
"""Human-readable terminal output (Rich). Only used when stdout is a terminal.
|
|
2
|
+
|
|
3
|
+
Every application is shown with its name next to the ID (D4).
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from typing import TYPE_CHECKING, Any
|
|
9
|
+
|
|
10
|
+
from previty_cli.api import models as m
|
|
11
|
+
from previty_cli.output import clean
|
|
12
|
+
|
|
13
|
+
if TYPE_CHECKING:
|
|
14
|
+
from rich.console import Console
|
|
15
|
+
from rich.text import Text
|
|
16
|
+
|
|
17
|
+
_STATUS_STYLE = {
|
|
18
|
+
"fail_critical": "bold red",
|
|
19
|
+
"fail": "red",
|
|
20
|
+
"unclear": "yellow",
|
|
21
|
+
"pass": "green",
|
|
22
|
+
"out_of_scope": "dim",
|
|
23
|
+
"completed": "green",
|
|
24
|
+
"failed": "red",
|
|
25
|
+
"running": "cyan",
|
|
26
|
+
"queued": "dim",
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _text(value: object, style: str = "") -> Text:
|
|
31
|
+
from rich.text import Text
|
|
32
|
+
|
|
33
|
+
return Text(clean(value), style=style)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _opt(value: object) -> str:
|
|
37
|
+
return "-" if value in (None, "") else clean(value)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def short_commit(sha: str | None) -> str:
|
|
41
|
+
return sha[:7] if sha else "-"
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _when(value: Any) -> str:
|
|
45
|
+
if value is None:
|
|
46
|
+
return "-"
|
|
47
|
+
try:
|
|
48
|
+
return str(value.strftime("%Y-%m-%d %H:%M UTC"))
|
|
49
|
+
except AttributeError:
|
|
50
|
+
return clean(value)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _table(console: Console, columns: list[str], rows: list[list[Any]]) -> None:
|
|
54
|
+
from rich.table import Table
|
|
55
|
+
|
|
56
|
+
table = Table(show_header=True, header_style="bold", box=None, pad_edge=False)
|
|
57
|
+
for col in columns:
|
|
58
|
+
table.add_column(col, overflow="fold")
|
|
59
|
+
for row in rows:
|
|
60
|
+
table.add_row(*[c if hasattr(c, "stylize") else _text(c) for c in row])
|
|
61
|
+
console.print(table)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def app_header(console: Console, name: str | None, app_id: object) -> None:
|
|
65
|
+
label = f"{clean(name)} ({app_id})" if name else f"{app_id}"
|
|
66
|
+
console.print(_text(f"Application: {label}", "bold"))
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def kv(console: Console, label: str, value: object, style: str = "") -> None:
|
|
70
|
+
from rich.text import Text
|
|
71
|
+
|
|
72
|
+
line = Text(f"{label}: ", style="dim")
|
|
73
|
+
line.append(clean(value), style=style)
|
|
74
|
+
console.print(line, soft_wrap=True)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def whoami(console: Console, me: m.PublicMe) -> None:
|
|
78
|
+
kv(console, "User", f"{_opt(me.user.name)} <{_opt(me.user.email)}> ({me.user.id})")
|
|
79
|
+
kv(console, "Organization", f"{_opt(me.organization.name)} ({me.organization.id})")
|
|
80
|
+
kv(console, "Role", _opt(me.role))
|
|
81
|
+
key = me.key
|
|
82
|
+
kv(console, "API key", f"{key.name} ({key.prefix})")
|
|
83
|
+
kv(console, "Permissions", ", ".join(key.permissions) or "-")
|
|
84
|
+
kv(console, "Created", _when(key.created_at))
|
|
85
|
+
kv(console, "Expires", _when(key.expires_at))
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def apps(console: Console, data: m.PublicApplicationList) -> None:
|
|
89
|
+
if not data.items:
|
|
90
|
+
console.print("No applications.")
|
|
91
|
+
return
|
|
92
|
+
_table(
|
|
93
|
+
console,
|
|
94
|
+
["ID", "NAME", "OWNER", "ACCESS"],
|
|
95
|
+
[[a.id, a.name, "yes" if a.is_owner else "no", a.access] for a in data.items],
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def readiness(console: Console, r: m.PublicReadiness) -> None:
|
|
100
|
+
app_header(console, r.application_name, r.application_id)
|
|
101
|
+
if r.can_start_check:
|
|
102
|
+
console.print(_text("Ready: a check can be started.", "green"))
|
|
103
|
+
else:
|
|
104
|
+
console.print(_text("Not ready: a check cannot be started.", "red"))
|
|
105
|
+
for title, reasons, style in (
|
|
106
|
+
("Blocking", r.blocking, "red"),
|
|
107
|
+
("Warnings", r.warnings, "yellow"),
|
|
108
|
+
):
|
|
109
|
+
if reasons:
|
|
110
|
+
console.print(_text(f"{title}:", "bold"))
|
|
111
|
+
for reason in reasons:
|
|
112
|
+
extra = (
|
|
113
|
+
f" [source {reason.data_source_id}]"
|
|
114
|
+
if reason.data_source_id
|
|
115
|
+
else ""
|
|
116
|
+
)
|
|
117
|
+
console.print(_text(f" {reason.code}: {reason.message}{extra}", style))
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def sources(console: Console, data: m.PublicDataSourceList) -> None:
|
|
121
|
+
app_header(console, data.application_name, data.application_id)
|
|
122
|
+
if not data.items:
|
|
123
|
+
console.print("No data sources.")
|
|
124
|
+
return
|
|
125
|
+
_table(
|
|
126
|
+
console,
|
|
127
|
+
["ID", "NAME", "PROVIDER", "REPOSITORY", "BRANCH", "LAST COMMIT", "STATUS"],
|
|
128
|
+
[
|
|
129
|
+
[
|
|
130
|
+
s.id,
|
|
131
|
+
s.name,
|
|
132
|
+
s.provider,
|
|
133
|
+
_opt(s.repository),
|
|
134
|
+
_opt(s.branch),
|
|
135
|
+
short_commit(s.last_checked_commit or s.current_commit),
|
|
136
|
+
s.status + (" (stale)" if s.is_stale else ""),
|
|
137
|
+
]
|
|
138
|
+
for s in data.items
|
|
139
|
+
],
|
|
140
|
+
)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def branches(console: Console, source_id: str, data: m.PublicBranchList) -> None:
|
|
144
|
+
kv(console, "Data source", source_id)
|
|
145
|
+
if not data.items:
|
|
146
|
+
console.print("No branches.")
|
|
147
|
+
return
|
|
148
|
+
_table(
|
|
149
|
+
console,
|
|
150
|
+
["", "BRANCH", "COMMIT", "PROTECTED"],
|
|
151
|
+
[
|
|
152
|
+
[
|
|
153
|
+
"*" if b.is_current else "",
|
|
154
|
+
b.name,
|
|
155
|
+
short_commit(b.commit_sha),
|
|
156
|
+
"yes" if b.protected else "no",
|
|
157
|
+
]
|
|
158
|
+
for b in data.items
|
|
159
|
+
],
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def check(console: Console, c: m.PublicCheck, *, header: bool = True) -> None:
|
|
164
|
+
if header:
|
|
165
|
+
app_header(console, c.application_name, c.application_id)
|
|
166
|
+
kv(console, "Check", f"{c.name} ({c.id})")
|
|
167
|
+
status = c.status.value + (" (retrying)" if c.retrying else "")
|
|
168
|
+
kv(console, "Status", status, _STATUS_STYLE.get(c.status.value, ""))
|
|
169
|
+
if c.progress:
|
|
170
|
+
p = c.progress
|
|
171
|
+
kv(console, "Progress", f"{p.checked}/{p.total} ({p.percent}%)")
|
|
172
|
+
kv(console, "Started", f"{_when(c.started_at)} via {_opt(c.started_via.value)}")
|
|
173
|
+
if c.completed_at:
|
|
174
|
+
kv(console, "Completed", _when(c.completed_at))
|
|
175
|
+
for s in c.sources or []:
|
|
176
|
+
where = clean(s.repository or s.name)
|
|
177
|
+
if s.branch or s.commit:
|
|
178
|
+
where += f" {_opt(s.branch)}@{short_commit(s.commit)}"
|
|
179
|
+
console.print(_text(f" Source: {where} [{s.provider}]"))
|
|
180
|
+
if c.summary:
|
|
181
|
+
s2 = c.summary
|
|
182
|
+
kv(
|
|
183
|
+
console,
|
|
184
|
+
"Summary",
|
|
185
|
+
f"{s2.total} requirements: {s2.fail_critical} critical, {s2.fail} fail, "
|
|
186
|
+
f"{s2.unclear} unclear, {s2.out_of_scope} out of scope, {s2.pass_} pass",
|
|
187
|
+
)
|
|
188
|
+
if c.failure:
|
|
189
|
+
kv(console, "Failure", f"{c.failure.code}: {_opt(c.failure.summary)}", "red")
|
|
190
|
+
if c.web_url:
|
|
191
|
+
kv(console, "Web", c.web_url)
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def check_list(console: Console, data: m.PublicCheckList) -> None:
|
|
195
|
+
app_header(console, data.application_name, data.application_id)
|
|
196
|
+
if not data.items:
|
|
197
|
+
console.print("No checks.")
|
|
198
|
+
return
|
|
199
|
+
_table(
|
|
200
|
+
console,
|
|
201
|
+
["ID", "NAME", "STATUS", "STARTED", "FAIL", "UNCLEAR", "VIA"],
|
|
202
|
+
[
|
|
203
|
+
[
|
|
204
|
+
c.id,
|
|
205
|
+
c.name,
|
|
206
|
+
_text(c.status.value, _STATUS_STYLE.get(c.status.value, "")),
|
|
207
|
+
_when(c.started_at),
|
|
208
|
+
(c.summary.fail + c.summary.fail_critical) if c.summary else "-",
|
|
209
|
+
c.summary.unclear if c.summary else "-",
|
|
210
|
+
c.started_via.value,
|
|
211
|
+
]
|
|
212
|
+
for c in data.items
|
|
213
|
+
],
|
|
214
|
+
)
|
|
215
|
+
if data.total > len(data.items):
|
|
216
|
+
console.print(_text(f"Showing {len(data.items)} of {data.total}.", "dim"))
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def results(console: Console, data: m.PublicFindingList) -> None:
|
|
220
|
+
app_header(console, data.application_name, data.application_id)
|
|
221
|
+
kv(console, "Check", f"{data.check_name} ({data.check_id})")
|
|
222
|
+
console.print(_text(data.content_notice, "dim"))
|
|
223
|
+
if not data.items:
|
|
224
|
+
console.print("No findings.")
|
|
225
|
+
return
|
|
226
|
+
from rich.text import Text
|
|
227
|
+
|
|
228
|
+
rows: list[list[Any]] = []
|
|
229
|
+
for f in data.items:
|
|
230
|
+
req = f.requirement
|
|
231
|
+
mo = f.model_output
|
|
232
|
+
where = ""
|
|
233
|
+
if req:
|
|
234
|
+
where = " / ".join(clean(p) for p in (req.section, req.title) if p)
|
|
235
|
+
if req.severity:
|
|
236
|
+
where += f" [{clean(req.severity)}]"
|
|
237
|
+
finding = Text()
|
|
238
|
+
if mo and mo.title:
|
|
239
|
+
finding.append(clean(mo.title) + "\n", style="bold")
|
|
240
|
+
if mo and mo.explanation:
|
|
241
|
+
finding.append(clean(mo.explanation))
|
|
242
|
+
if f.check_error:
|
|
243
|
+
finding.append(
|
|
244
|
+
clean(f"{f.check_error.code}: {f.check_error.message or ''}")
|
|
245
|
+
)
|
|
246
|
+
rows.append(
|
|
247
|
+
[
|
|
248
|
+
_text(f.status.value, _STATUS_STYLE.get(f.status.value, "")),
|
|
249
|
+
where,
|
|
250
|
+
finding,
|
|
251
|
+
(mo.suggested_fix if mo else None) or "-",
|
|
252
|
+
]
|
|
253
|
+
)
|
|
254
|
+
_table(console, ["STATUS", "REQUIREMENT", "FINDING", "SUGGESTED FIX"], rows)
|
|
255
|
+
if data.total > len(data.items):
|
|
256
|
+
console.print(_text(f"Showing {len(data.items)} of {data.total}.", "dim"))
|
previty_cli/py.typed
ADDED
|
File without changes
|
previty_cli/redact.py
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"""Keep API keys out of everything the CLI prints."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
|
|
7
|
+
# Whole tokens only, and never an already masked one (ends in "…").
|
|
8
|
+
_KEY_PATTERN = re.compile(r"prv_[A-Za-z0-9_]+(?![A-Za-z0-9_…])")
|
|
9
|
+
_known_secrets: set[str] = set()
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def register_secret(secret: str) -> None:
|
|
13
|
+
"""Remember a secret so :func:`scrub` removes it even if it has no prv_ prefix."""
|
|
14
|
+
if secret:
|
|
15
|
+
_known_secrets.add(secret)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def mask_key(key: str) -> str:
|
|
19
|
+
"""Show only the display prefix (``prv_<id>``) of a key."""
|
|
20
|
+
parts = key.split("_")
|
|
21
|
+
if len(parts) >= 3 and parts[0] == "prv":
|
|
22
|
+
return f"prv_{parts[1]}…"
|
|
23
|
+
return "…"
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def scrub(text: str) -> str:
|
|
27
|
+
"""Replace every known secret and anything shaped like a key by its mask."""
|
|
28
|
+
for secret in sorted(_known_secrets, key=len, reverse=True):
|
|
29
|
+
text = text.replace(secret, mask_key(secret))
|
|
30
|
+
return _KEY_PATTERN.sub(lambda m: mask_key(m.group(0)), text)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def reset_for_tests() -> None:
|
|
34
|
+
_known_secrets.clear()
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: previty-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Command-line interface for the Previty public API
|
|
5
|
+
Project-URL: Homepage, https://previty.de
|
|
6
|
+
Author: Previty GmbH
|
|
7
|
+
License-Expression: LicenseRef-Proprietary
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: cli,compliance,previty
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Typing :: Typed
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Requires-Dist: httpx<1,>=0.27
|
|
20
|
+
Requires-Dist: pydantic<3,>=2.7
|
|
21
|
+
Requires-Dist: typer<1,>=0.28
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# previty-cli
|
|
25
|
+
|
|
26
|
+
The `previty` command-line interface for the Previty public API: start compliance
|
|
27
|
+
checks, follow them and read their findings from your terminal, CI pipeline or
|
|
28
|
+
coding agent.
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
Python 3.10 or newer is required (not needed with `uvx`, uv brings its own Python).
|
|
33
|
+
Use an isolated install; a plain `pip install` into a project environment can clash
|
|
34
|
+
with that project's dependencies.
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
uv tool install previty-cli # recommended
|
|
38
|
+
pipx install previty-cli # alternative
|
|
39
|
+
uvx previty-cli check list --app <id> # no install, e.g. in CI and for agents
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Quick start
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
previty login # hidden prompt; or: printf %s "$KEY" | previty login
|
|
46
|
+
previty apps list
|
|
47
|
+
previty readiness --app <app-id>
|
|
48
|
+
previty check run --app <app-id> --wait
|
|
49
|
+
previty results <check-id> --status fail,unclear --format markdown
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Create an API key in the web app under Settings, User, API keys (the organization
|
|
53
|
+
must have API access turned on). The key is never accepted as a command-line
|
|
54
|
+
argument.
|
|
55
|
+
|
|
56
|
+
## Commands
|
|
57
|
+
|
|
58
|
+
| Command | What it does |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `previty login [--with-token]` | Hidden prompt in a terminal; otherwise (or with `--with-token`) reads the key from stdin. Validates it with `GET /me`, then stores it |
|
|
61
|
+
| `previty logout` | Removes the stored key |
|
|
62
|
+
| `previty whoami` | User, organization, key prefix, permissions, expiry |
|
|
63
|
+
| `previty apps list` | Applications you can access: ID, name, owner |
|
|
64
|
+
| `previty readiness --app <id>` | Can a check be started, and if not, why. Exit 0 if yes, 7 if not |
|
|
65
|
+
| `previty sources list --app <id>` | Data sources: ID, name, provider, repository, branch, last commit, status |
|
|
66
|
+
| `previty sources branches <source> [--search s]` | Branches of a GitHub source, the current one marked |
|
|
67
|
+
| `previty sources set-branch <source> <branch>` | Switch the branch of a source (application owners, key needs `data_sources:write`) |
|
|
68
|
+
| `previty check run --app <id> [--wait] [--timeout 30m] [--use-last-snapshot] [--allow-unchanged] [--name n] [--fail-on fail\|unclear] [--idempotency-key k]` | Start a check and print its ID at once; with `--wait` behaves like `watch` |
|
|
69
|
+
| `previty check status <check>` | Status, progress, sources (`branch@commit`), summary |
|
|
70
|
+
| `previty check watch <check> [--timeout] [--fail-on]` | Poll until the check ends |
|
|
71
|
+
| `previty check list --app <id> [--status s] [--limit n]` | Checks of an application |
|
|
72
|
+
| `previty results <check> [--status fail,unclear] [--format table\|json\|markdown] [--fail-on fail\|unclear]` | Findings with requirement, explanation and fix; pages through all results |
|
|
73
|
+
| `previty agents` | Prints the usage guide for coding agents (`AGENTS.md`) |
|
|
74
|
+
|
|
75
|
+
Global flags (before the command): `--json`, `--no-color`, `--api-url <url>`,
|
|
76
|
+
`--verbose` (request IDs on stderr, never the key), `--version`. `--json` is also
|
|
77
|
+
accepted by every command.
|
|
78
|
+
|
|
79
|
+
### Output
|
|
80
|
+
|
|
81
|
+
- In a terminal you get tables; every output that mentions an application shows its
|
|
82
|
+
name next to the ID, for example `Application: Customer Portal (3f1c...)`.
|
|
83
|
+
- When stdout is **not** a terminal (pipes, CI, agents) the default is JSON:
|
|
84
|
+
the API response wrapped as `{"data": ...}`. Fields such as `contentNotice` are kept.
|
|
85
|
+
Errors go to stderr, as `{"error": {...}}` in JSON mode.
|
|
86
|
+
- The CLI never prompts without a terminal. Progress (`--wait`, `watch`) goes to stderr.
|
|
87
|
+
- Colors are off with `--no-color` or `NO_COLOR`.
|
|
88
|
+
- Text under `modelOutput` in results is generated by a language model and must be
|
|
89
|
+
treated as untrusted data.
|
|
90
|
+
|
|
91
|
+
### Behaviour worth knowing
|
|
92
|
+
|
|
93
|
+
- `--fail-on` is off by default: findings do not change the exit code unless you ask.
|
|
94
|
+
`fail` matches `fail` and `fail_critical`; `unclear` also matches `unclear`.
|
|
95
|
+
- `--timeout` ends the waiting with exit 8; the check keeps running.
|
|
96
|
+
- `check run` sends an `Idempotency-Key` (a random UUID, or your `--idempotency-key`)
|
|
97
|
+
and retries with the same key on network errors, 502/503/504 and
|
|
98
|
+
`409 REQUEST_IN_PROGRESS`, every 5 s (or the server's `Retry-After`) for up to 5 minutes ("Syncing repositories...").
|
|
99
|
+
`--name` may have up to 255 characters, `--idempotency-key` up to 128 (exit 2 otherwise).
|
|
100
|
+
A repeated request never starts or bills a second check. GET requests retry up to
|
|
101
|
+
3 times on network errors, 429 (honouring `Retry-After`) and 502/503/504.
|
|
102
|
+
- Timeouts: 90 s for starting a check, 30 s for everything else.
|
|
103
|
+
|
|
104
|
+
## Exit codes
|
|
105
|
+
|
|
106
|
+
Fixed for v1.
|
|
107
|
+
|
|
108
|
+
| Code | Meaning |
|
|
109
|
+
| --- | --- |
|
|
110
|
+
| 0 | Success |
|
|
111
|
+
| 1 | Unexpected or server error, network failure after retries |
|
|
112
|
+
| 2 | Usage error (bad flags, would need a prompt without a terminal, host not allowed) |
|
|
113
|
+
| 3 | Authentication (no key, invalid, expired, org API access off, membership removed) |
|
|
114
|
+
| 4 | Permission (key scope missing, not application owner) |
|
|
115
|
+
| 5 | Not found |
|
|
116
|
+
| 6 | Quota or billing (`CHECK_LIMIT_REACHED`, `SUBSCRIPTION_REQUIRED`) |
|
|
117
|
+
| 7 | Precondition or conflict (sync failed, no changes, check running, branch errors, not ready) |
|
|
118
|
+
| 8 | Wait timeout (`--timeout`) |
|
|
119
|
+
| 9 | The check ended as `failed` |
|
|
120
|
+
| 10 | `--fail-on` matched findings |
|
|
121
|
+
| 11 | Rate limited or blocked at the edge |
|
|
122
|
+
|
|
123
|
+
## Configuration and security
|
|
124
|
+
|
|
125
|
+
| | |
|
|
126
|
+
| --- | --- |
|
|
127
|
+
| Credentials file | `credentials.json` (`{apiUrl, apiKey}`), mode 0600 in a 0700 directory, written atomically |
|
|
128
|
+
| Location | Linux and macOS: `$XDG_CONFIG_HOME/previty/`, default `~/.config/previty/`. Windows: `%APPDATA%\previty\` |
|
|
129
|
+
| `PREVITY_CONFIG_DIR` | Overrides the location |
|
|
130
|
+
| `PREVITY_API_KEY` | Takes precedence over the stored key |
|
|
131
|
+
| `PREVITY_API_URL` | Overrides the stored URL (default `https://api.previty.de/public/v1`) |
|
|
132
|
+
| `PREVITY_ALLOW_INSECURE_LOCALHOST=1` | Allows `http://localhost` / `127.0.0.1` for development |
|
|
133
|
+
|
|
134
|
+
The key is only ever sent to `api.previty.de` and `api.dev.previty.de` over https;
|
|
135
|
+
any other host is a usage error before a request is made. Redirects are never
|
|
136
|
+
followed. Tracebacks are off, and the key is masked in all output. The CLI warns if
|
|
137
|
+
the credentials file is readable by other users. On Windows, POSIX modes do not
|
|
138
|
+
apply; the per-user `AppData` folder is relied on.
|
|
139
|
+
|
|
140
|
+
## Development
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
uv sync
|
|
144
|
+
./.husky/install.sh # conventional-commit and branch-name hooks
|
|
145
|
+
uv run ruff check . && uv run ruff format --check .
|
|
146
|
+
uv run mypy --strict src
|
|
147
|
+
uv run pytest
|
|
148
|
+
uv run python scripts/measure_startup.py # previty --help budget: 300 ms
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Commits follow `<type>(scope): <description>` on a branch named
|
|
152
|
+
`feature/<TICKET>-<title>`, like the other Previty repositories.
|
|
153
|
+
|
|
154
|
+
### API models
|
|
155
|
+
|
|
156
|
+
`src/previty_cli/api/models.py` is generated with `datamodel-code-generator` from a
|
|
157
|
+
pinned copy of the server's OpenAPI document, `openapi/public-v1.json`. Never edit
|
|
158
|
+
either file by hand. To update them:
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
uv run python scripts/sync_openapi.py ../workspace-service/openapi/public-v1.json
|
|
162
|
+
# or from a running API:
|
|
163
|
+
uv run python scripts/sync_openapi.py https://api.dev.previty.de/public/v1/openapi.json
|
|
164
|
+
uv run python scripts/sync_openapi.py # regenerate from the pin only
|
|
165
|
+
uv run python scripts/sync_openapi.py --check # what CI runs: fail on drift
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### Smoke test
|
|
169
|
+
|
|
170
|
+
`PREVITY_API_KEY=<dev key> scripts/smoke_dev.sh` exercises the CLI against
|
|
171
|
+
`api.dev.previty.de` (see the script for the optional `SMOKE_APP_ID` and
|
|
172
|
+
`SMOKE_RUN_CHECK` switches).
|
|
173
|
+
|
|
174
|
+
### Release
|
|
175
|
+
|
|
176
|
+
Bump `version` in `pyproject.toml` and `src/previty_cli/__init__.py`, merge, then push
|
|
177
|
+
a tag `vX.Y.Z`. The release workflow builds the wheel and sdist and publishes to PyPI
|
|
178
|
+
with trusted publishing (OIDC, no stored token).
|
|
179
|
+
|
|
180
|
+
## Licence
|
|
181
|
+
|
|
182
|
+
Proprietary, (c) Previty GmbH. All rights reserved. See `LICENSE`.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
previty_cli/AGENTS.md,sha256=-fZvVs4kEw9tlf9RYVQMlFUgm5_8x8J4jzfSYDiA7NA,3434
|
|
2
|
+
previty_cli/__init__.py,sha256=68yc22rBel5kUeEMvCU7w9x_KvhD47EyTGtr-2W2B1I,61
|
|
3
|
+
previty_cli/__main__.py,sha256=J3gGxIuyrgAN0o3R3O6xw4GrytQQZtkDDxPWZzgoDok,72
|
|
4
|
+
previty_cli/app.py,sha256=1_qEoujO16ys7HbgcPn_HcUHL7-X_y5929M1V4cf2DQ,4829
|
|
5
|
+
previty_cli/clock.py,sha256=C72bJKFRewiSM4drv6sLUdvyNq-F9iACSqaZTOuB_U8,242
|
|
6
|
+
previty_cli/config.py,sha256=wR1zWt3vh-eqpLa661QMm4CJgwIzzpzeVPYQTPUmN7g,6478
|
|
7
|
+
previty_cli/errors.py,sha256=xQVFdPy5u3cqYozjH1fMe3mTkttot-tsYkBzNqD8fXU,4230
|
|
8
|
+
previty_cli/exit_codes.py,sha256=umCxC3nLChhHiisAGi6A5rhyO1FA14C9nK2w7-uVmjk,1566
|
|
9
|
+
previty_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
10
|
+
previty_cli/redact.py,sha256=fLnks2IFBu-7SPkX-9I0cgUWa2DV9FhXDOR4MPMDDZ8,1033
|
|
11
|
+
previty_cli/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
12
|
+
previty_cli/api/client.py,sha256=KTrdb7D0X7mrrJ2WlmyHKc2e59j8ibKZfya7jPSLOX0,12883
|
|
13
|
+
previty_cli/api/models.py,sha256=JdlArVLsNe1b4Hu6OZE9RNEscHEUZe4CArQTcZ8iVQk,19188
|
|
14
|
+
previty_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
15
|
+
previty_cli/commands/_common.py,sha256=OKpQariYVvEVj03J6pC47km6xYJ2ZIjFnsYuVnmb2vQ,3276
|
|
16
|
+
previty_cli/commands/agents.py,sha256=M59OD9KYkjhBR6osBrq338J3cQDs7Ghbb87-wfoHG7c,637
|
|
17
|
+
previty_cli/commands/apps.py,sha256=ioTR7AGGSNpjDqFGW7UEegTwdfHr83BBkzPLaUgBVCQ,725
|
|
18
|
+
previty_cli/commands/auth.py,sha256=pSvuG8aE6xgiU2ygJGlWi8MnrrCq-FHFWbj9gFqb1hw,3293
|
|
19
|
+
previty_cli/commands/checks.py,sha256=2x1BrUHxEzRWHUB2x5ix3i6gKDJ0k1QRQaVVXiBzVJU,9836
|
|
20
|
+
previty_cli/commands/readiness.py,sha256=jhFkQzq7T7oF2bXZqy_qJR4WmsK0S21rXQM5oQ6cr9A,853
|
|
21
|
+
previty_cli/commands/results.py,sha256=oVwGKCobohdNwZku1Ce7ihnUcN79ODCJ-d9rztn6WtU,2331
|
|
22
|
+
previty_cli/commands/sources.py,sha256=gjm_nk4YFSHbMJg2dnrZDaBowaRDGuVctf9ysXEOzr0,3081
|
|
23
|
+
previty_cli/output/__init__.py,sha256=HgAbUWJsYhdEq2chmTc2dL_F3HzhcYS2rW_HnZvdFjU,942
|
|
24
|
+
previty_cli/output/json.py,sha256=-vD7Tz7SuuoJpZLvtx5wS121o1lB4i-ZrlGSFaGh5a0,599
|
|
25
|
+
previty_cli/output/markdown.py,sha256=rSE8W5GQTQvZzDGOH-3BUQt-2EZN6qGfTGkHrWsUkko,2279
|
|
26
|
+
previty_cli/output/table.py,sha256=In1oLhRPmRwU03eAaBZPlOx7zOKtimsJu4IlUcASUAQ,8440
|
|
27
|
+
previty_cli-0.1.0.dist-info/METADATA,sha256=AlpZ7Gkr-rC91tRe236p6ab_6PbTPBzuggJMmA_M3G8,8361
|
|
28
|
+
previty_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
29
|
+
previty_cli-0.1.0.dist-info/entry_points.txt,sha256=K_fYeNqwzDaG2h1ksDsSf9A5oLSnmla7PkWsMr0iI5M,49
|
|
30
|
+
previty_cli-0.1.0.dist-info/licenses/LICENSE,sha256=tjR0YOvOLdcPzJEfuY88QcCSPvOcuT7ViiyTUpDRSrE,555
|
|
31
|
+
previty_cli-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
Copyright (c) 2026 Previty GmbH. All rights reserved.
|
|
2
|
+
|
|
3
|
+
This software and its source code are proprietary to Previty GmbH. No licence
|
|
4
|
+
is granted to copy, modify, distribute or sublicense it, except that customers
|
|
5
|
+
of Previty GmbH may install and run the unmodified package to use the Previty
|
|
6
|
+
service in accordance with their agreement with Previty GmbH.
|
|
7
|
+
|
|
8
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
9
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
10
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|