A typed decision and every detector probability will appear here.
:
{percent(decision.risk)}
Aggregate risk
{decision.model}
{decision.reason}
+ {decision.verdict === "indeterminate" &&
The classifier did not complete an evaluation. Check Settings → Classifier provider. Local-only profiles work without a TypeSafe key; semantic profiles need a configured provider. The action above follows this profile’s failure policy.
}
{[...decision.detectors].sort((a, b) => b.weightedProbability - a.weightedProbability).map((detector) =>
{detector.name}{percent(detector.probability)}
= .8 ? "h-full bg-accent transition-all duration-500" : detector.probability >= .55 ? "h-full bg-accent transition-all duration-500" : "h-full bg-surface-hover transition-all duration-500"} style={{ width: `${Math.max(1, detector.probability * 100)}%` }} />
)}
}
diff --git a/packages/classifiers/src/index.ts b/packages/classifiers/src/index.ts
index 90572ea..08cc74a 100644
--- a/packages/classifiers/src/index.ts
+++ b/packages/classifiers/src/index.ts
@@ -132,7 +132,7 @@ export function buildFailureDecision(
action: closed ? "block" : "allow",
risk: closed ? 1 : 0,
confidence: 0,
- reason: `Classifier unavailable; applied fail-${input.profile.failMode} policy.`,
+ reason: `${error instanceof ClassifierConfigurationError ? error.message : "Classifier unavailable."} Applied fail-${input.profile.failMode} policy; this is not a detected attack.`,
detectors: [],
model: input.profile.model,
provider: input.provider.mode,
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 658e81d..b72e520 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -6,35 +6,36 @@ running Pyro server. The CLI does not start services.
## Install
-With Node.js 22.13 or newer and pnpm 11.10.0, run from the Pyro repository:
+The CLI is published on npm. With Node.js 22.13+ and pnpm:
```sh
-pnpm install --frozen-lockfile
-pnpm --filter @delvisor/pyro run build
-pnpm add --global ./packages/cli
+pnpm add --global @delvisor/pyro
pyro --help
```
-For a standalone install, build an npm tarball and install it. It includes both API
-contracts and has no dependency on other Pyro packages or the source checkout:
+A running Pyro server is required. Follow the [Docker quickstart](https://delvisor.com/pyro/docs#setup) to start one without cloning the repository, or connect to an existing instance. The CLI does not host the gateway, dashboard or database.
+
+CLI 0.2.0 adds `pyro doctor` (server checks) and `pyro doctor --semantic` (also requires classifier configuration). No prompts or credentials are sent to a model during diagnostics. Missing semantic configuration does not prevent local-only profiles from working.
+
+For development from a checkout:
```sh
-mkdir -p artifacts
+pnpm install --frozen-lockfile
pnpm --filter @delvisor/pyro pack --pack-destination artifacts
-pnpm add --global ./artifacts/delvisor-pyro-0.1.0.tgz
+# Install the generated tarball from artifacts/.
```
-The package is prepared as `@delvisor/pyro`; it has not been published to npm. A registry
-install with `pnpm add --global @delvisor/pyro` will be available after publication.
-
## Start with your dashboard
+First download and import [local-secrets.yaml](https://delvisor.com/pyro/profiles/local-secrets.yaml) after signing in: `pyro profiles import --file ./local-secrets.yaml`. That preset checks credential shapes locally and needs no TypeSafe key. Semantic profiles require a key in Settings → Classifier provider and send inputs to that provider. A missing or unavailable classifier produces an indeterminate verdict and follows the configured fail mode; it does not mean an attack was detected.
+
+
```sh
pyro auth login # hidden administrator-password prompt
pyro overview
pyro profiles list
pyro apps list
-pyro playground 'Summarize this document.'
+pyro playground 'Summarize this document.' --profile local-secrets
pyro activity list --limit 20
```
diff --git a/packages/cli/package.json b/packages/cli/package.json
index d1dbc27..59acab1 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,7 +1,7 @@
{
"name": "@delvisor/pyro",
- "version": "0.1.0",
- "description": "The Pyro command line: classify inputs and manage your firewall.",
+ "version": "0.2.0",
+ "description": "Classify inputs, inspect decisions, and manage a self-hosted Pyro server.",
"type": "module",
"license": "Apache-2.0",
"bin": {
@@ -36,5 +36,14 @@
"publishConfig": {
"access": "public",
"registry": "https://registry.npmjs.org/"
+ },
+ "homepage": "https://delvisor.com/pyro/docs",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/DelvisorLabs/Pyro.git",
+ "directory": "packages/cli"
+ },
+ "bugs": {
+ "url": "https://github.com/DelvisorLabs/Pyro/issues"
}
}
diff --git a/packages/cli/scripts/test-install.mjs b/packages/cli/scripts/test-install.mjs
index a485980..1f679fe 100644
--- a/packages/cli/scripts/test-install.mjs
+++ b/packages/cli/scripts/test-install.mjs
@@ -22,7 +22,7 @@ try {
await exec("pnpm", ["add", "--global", "--ignore-scripts", "--global-dir", join(directory, "global"), "--global-bin-dir", bin, resolve(directory, filename)], options);
const executable = join(bin, "pyro");
const { stdout } = await exec(executable, ["--help"], options);
- assert.match(stdout, /Pyro — classify inputs/);
+ assert.match(stdout, /Pyro/);
const version = await exec(executable, ["--version"], options);
assert.equal(version.stdout.trim(), manifest.version);
const spec = await exec(executable, ["spec", "control"], options);
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index f880acc..6500a0b 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -5,6 +5,7 @@ import { configPath, normalizeUrl, readConfig, settings, writeConfig, type Globa
import { jsonSource, parseValue, passwordPrompt, readStdin, source } from "./input.js";
import { bodyProperties, endpoints, kebab, optionKey, specs, type Endpoint } from "./spec.js";
import { CliError, credentials, request, stream } from "./transport.js";
+import { diagnose } from "./doctor.js";
type Options = Record
;
@@ -134,15 +135,24 @@ async function runEndpoint(endpoint: Endpoint, command: Command, args: string[])
export function createProgram(): Command {
const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string };
const program = new Command().name("pyro").version(version)
- .description("Pyro — classify inputs, observe decisions, and configure your firewall.")
+ .description("Pyro — classify inputs and manage a running Pyro server.")
.option("--gateway-url ", "gateway URL (PYRO_GATEWAY_URL; default http://localhost:8080)")
.option("--control-url ", "dashboard API URL (PYRO_CONTROL_URL; default http://localhost:8081)")
.option("--config ", "config file (PYRO_CONFIG or ~/.config/pyro/config.json)")
.option("--timeout ", "request/authentication timeout (PYRO_TIMEOUT_MS; default 130000)")
.option("--json", "compact JSON output for scripts (streams always use NDJSON)")
.showHelpAfterError()
- .addHelpText("after", "\nGet started:\n pyro auth login Sign in with your dashboard password\n pyro profiles list Manage the same profiles as the dashboard\n pyro playground 'hello' Classify using your dashboard session\n PYRO_API_KEY=pf_… pyro classify 'hello'\n\nObserve: overview, usage, activity, playground\nConfigure: profiles, apps, keys, webhooks, settings\nUse `pyro --help` for field flags and examples. No service is started automatically.");
+ .addHelpText("after", "\nGet started (a running server is required):\n pyro doctor Check server connectivity and setup\n pyro auth login Sign in with your dashboard password\n pyro profiles list Manage the same profiles as the dashboard\n pyro playground 'hello' --profile local-secrets After importing the local-only preset\n PYRO_API_KEY=pf_… pyro classify 'hello'\n\nObserve: overview, usage, activity, playground\nConfigure: profiles, apps, keys, webhooks, settings\nUse `pyro --help` for field flags and examples. No service is started automatically.");
const groups = new Map([["", program]]);
+ program.command("doctor").description("Check server connectivity and semantic configuration without sending prompts")
+ .option("--semantic", "also require semantic classifier configuration")
+ .action(async (options: { semantic?: boolean }, command: Command) => {
+ const global = command.optsWithGlobals();
+ const report = await diagnose(settings(global, await readConfig(configPath(global))));
+ await output(report, global);
+ if (!report.localRulesReady) process.exitCode = 4;
+ else if (options.semantic && !report.semantic.ok) process.exitCode = 1;
+ });
const descriptions: Record = {
auth: "Dashboard authentication", profiles: "Profiles and the curated profile library",
apps: "Applications and local rules", keys: "Application API keys", webhooks: "Webhooks and delivery history",
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
new file mode 100644
index 0000000..140b3bf
--- /dev/null
+++ b/packages/cli/src/doctor.ts
@@ -0,0 +1,24 @@
+import { CliError, request } from "./transport.js";
+
+export async function diagnose(connection: { gateway: string; control: string; timeout: number }) {
+ const check = async (base: string, path: string) => {
+ try {
+ const result = await request(new URL(`${base}${path}`), "GET", {}, undefined, Math.min(connection.timeout, 5_000));
+ return { ok: true, status: result.response.status, detail: result.data };
+ } catch (error) {
+ return { ok: false, status: error instanceof CliError ? error.details?.status : undefined, detail: error instanceof Error ? error.message : "Check failed" };
+ }
+ };
+ const [gateway, control, semantic] = await Promise.all([
+ check(connection.gateway, "/v1/health"), check(connection.control, "/health"), check(connection.gateway, "/v1/ready"),
+ ]);
+ return {
+ gateway, control, semantic,
+ localRulesReady: gateway.ok && control.ok,
+ guidance: !gateway.ok || !control.ok
+ ? "Start the Pyro server with Docker, or set the URLs of an existing instance: https://delvisor.com/pyro/docs#setup. Installing the CLI does not start a server."
+ : !semantic.ok
+ ? "Local-only profiles work without a provider key. For semantic checks, add a TypeSafe key in Settings → Classifier provider, then run pyro doctor --semantic. Readiness checks configuration, not detector accuracy or provider availability."
+ : "Server checks passed. Semantic configuration is present; test your policy against representative traffic before enforcement.",
+ };
+}
diff --git a/packages/cli/src/transport.ts b/packages/cli/src/transport.ts
index 9206a76..c85fb76 100644
--- a/packages/cli/src/transport.ts
+++ b/packages/cli/src/transport.ts
@@ -26,7 +26,7 @@ export async function request(url: URL, method: string, headers: Record {
+ const config = join(await temporary(t), "config.json");
+ let configured = false;
+ const requests: string[] = [];
+ const { url } = await server(t, (req, res) => {
+ assert.equal(req.headers.authorization, undefined);
+ assert.equal(req.headers.cookie, undefined);
+ requests.push(req.url!);
+ res.writeHead(req.url === "/v1/ready" && !configured ? 503 : 200, { "content-type": "application/json" });
+ res.end(JSON.stringify({ status: configured ? "ready" : "not_ready" }));
+ });
+ await sessionConfig(config, url);
+ const local = await invoke(["doctor"], { config });
+ assert.equal(local.code, 0);
+ assert.equal(JSON.parse(local.stdout).localRulesReady, true);
+ assert.equal(JSON.parse(local.stdout).semantic.ok, false);
+ assert.equal((await invoke(["doctor", "--semantic"], { config })).code, 1);
+ configured = true;
+ assert.equal((await invoke(["doctor", "--semantic"], { config })).code, 0);
+ assert.ok(requests.every(path => ["/health", "/v1/health", "/v1/ready"].includes(path)));
+});
+
+test("doctor explains server setup when the server is unreachable", async t => {
+ const config = join(await temporary(t), "config.json");
+ const result = await invoke(["--gateway-url", "http://127.0.0.1:1", "--control-url", "http://127.0.0.1:1", "doctor"], { config });
+ assert.equal(result.code, 4);
+ assert.match(JSON.parse(result.stdout).guidance, /does not start a server/);
+});