Skip to content

[docs] Document certutil-missing warning in aspire doctor and certs clean #1436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
David Pine (IEvangelist) merged 1 commit into from
Aug 7, 2026
+27 −0
Merged

[docs] Document certutil-missing warning in aspire doctor and certs clean #1436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions src/frontend/src/content/docs/reference/cli/commands/aspire-certs-clean.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ description: Learn about the aspire certs clean command and its usage. This comm
---

import Include from '@components/Include.astro';
import { Aside } from '@astrojs/starlight/components';

## Name

Expand All @@ -19,6 +20,15 @@ aspire certs clean [options]

The `aspire certs clean` command removes all HTTPS development certificates. Use it when you want to reset local certificate state before trusting a new certificate or while troubleshooting HTTPS-related local development issues.

<Aside type="note">
On Linux, if `certutil` is unavailable, NSS certificate database cleanup for
Firefox and Chromium browsers is skipped, but `aspire certs clean` still
completes cleanup for the remaining certificate stores. Run `aspire doctor`
to check whether `certutil` is installed. Install it from your
distribution's NSS tools package, for example `libnss3-tools`, to enable
browser certificate trust cleanup.
</Aside>

## Options

The following options are available:
Expand Down
17 changes: 17 additions & 0 deletions src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ This command is useful for troubleshooting when you encounter issues with Aspire
- **Container checks**: Validates container runtime (Docker and/or Podman) availability, running status, and version. Reports which runtime is active and why (explicit configuration, auto-detected default, or auto-detected only runtime running)
- **Environment checks**: Reports operating system information (type, version, and Linux distro details when available) and validates environment variables and other settings, including the JavaScript toolchain required by TypeScript AppHosts (npm, pnpm, Yarn, or Bun)

<Aside type="note">
On Linux, `aspire doctor` reports a warning when `certutil` is unavailable.
Aspire uses `certutil` to query and update the NSS certificate databases used
by Firefox and Chromium browsers, so without it browser certificate trust may
be incomplete. Install `certutil` from your distribution's NSS tools package,
for example `libnss3-tools`, to resolve the warning.
</Aside>

The command displays results with clear status indicators:

- ✅ (green) - Check passed
Expand Down Expand Up @@ -128,6 +136,15 @@ AppHost version messages include an inline `(channel: <name>)` suffix; the same
channel data appears in JSON metadata as `identityChannel`,
`latestVersionChannel`, or `pinnedChannel` when available.

On Linux, when `certutil` is not installed, the Environment section reports a warning instead of failing the check:

```bash title="Aspire CLI"
Environment
✅ Operating system: Linux Ubuntu 24.04
⚠️ certutil is not available; browser certificate trust may be incomplete
Install certutil from your distribution's NSS tools package (for example, libnss3-tools).
```

When only Podman is running:

```bash title="Aspire CLI"
Expand Down
Loading