# Inkog Getting Started: First-Run Friction Audit

Audit date: 2026-09-02  
Reading path: Quickstart → Installation → Configuration → Dashboard Guide  
Priority: **P0** blocks the path or can silently produce an invalid result; **P1** is a material ambiguity, security risk, or unverifiable product step.

**Executive assessment.** The public onboarding path is not dependable as written. The most serious defects are not cosmetic: examples mix incompatible CLI grammars, document controls the released CLI does not expose, and can save plain text under a `.sarif` or `.json` filename without warning. The account-free path is also described differently across Quickstart, Installation, and the live product. The findings below follow the order in which a first-time reader encounters them, so the list can double as an editorial repair queue.

## 1. P0 — The first command hides its prerequisite

**Location and exact quote:** [Quickstart — Scan with npx](https://docs.inkog.io/getting-started#scan-with-npx-no-install): `npx -y @inkog-io/cli scan .`

**Failure point:** Quickstart does not say that Node.js is required; Node.js 18+ appears only on the next page. Without Node/npm, the first command is not found. “No install” is also imprecise: the npm wrapper downloads and caches an Inkog binary.

**Replacement wording:**

> **Prerequisite:** Node.js 18+ (`node --version`). This command downloads the npm wrapper and caches the Inkog binary at `~/.inkog/bin`; it does not install a global `inkog` command. Run `npx -y @inkog-io/cli scan .`. If Node is unavailable, choose an installation option below.

## 2. P0 — The no-install path switches to a global command

**Location and exact quote:** [Quickstart — One-Command Scan](https://docs.inkog.io/getting-started#one-command-scan): `inkog scan .`

**Failure point:** A reader who chose the npx path has not installed `inkog` globally or added it to `PATH`, so the next scan can fail with “command not found.” The page never says that the later examples assume permanent installation.

**Replacement wording:**

> Keep using the path you chose. **No install:** `npx -y @inkog-io/cli scan .`. **Permanent install:** `inkog .`. Every example below shows both forms.

## 3. P0 — API-key requirements contradict each other

**Location and exact quote:** [Quickstart — Get Your API Key](https://docs.inkog.io/getting-started#get-your-api-key): “Without an API key”; [Installation — API Key Setup](https://docs.inkog.io/getting-started/installation#api-key-setup-cloud-scanning): “required for all scans.”

**Failure point:** The reader cannot tell whether signup is optional. Current CLI source shows the actual split: an interactive no-key run attempts an anonymous preview of one selected file and shows at most two findings; full and non-interactive/CI scans require a key.

**Replacement wording:**

> No API key? In an interactive terminal, Inkog sends one selected file for an anonymous preview and shows at most two findings. Full-directory scans, CI/non-interactive runs, complete findings, remediation, and compliance reports require a free account and `INKOG_API_KEY`.

## 4. P1 — API-key setup is Unix-only

**Location and exact quote:** [Quickstart — Get Your API Key](https://docs.inkog.io/getting-started#get-your-api-key): `export INKOG_API_KEY=sk_live_your_key_here`

**Failure point:** Native Windows is listed as supported later, but `export` fails in PowerShell and Command Prompt.

**Replacement wording:**

> **Bash/Zsh:** `export INKOG_API_KEY='sk_live_…'`  
> **PowerShell:** `$env:INKOG_API_KEY = 'sk_live_…'`  
> **Command Prompt:** `set INKOG_API_KEY=sk_live_…`  
> For CI, store the value in the platform’s encrypted secret store.

## 5. P1 — Upload disclosure appears after the first scan command

**Location and exact quote:** [Quickstart — What Just Happened?](https://docs.inkog.io/getting-started#what-just-happened): “Secrets Redacted.”

**Failure point:** The first networked scan appears earlier. A user can scan proprietary code before learning that sanitized source is sent to the Inkog API. The privacy documentation also says prompts, business logic, configuration values, normal strings, and custom secret formats may not be redacted.

**Replacement wording:**

> **Data handling before you run this:** Inkog detects recognized credential patterns locally, replaces them, then sends sanitized source to the Inkog API for analysis. Prompts, business logic, configuration values, normal strings, and custom secret formats may still be sent. Only scan code you are authorized to upload. Read [Hybrid Privacy](https://docs.inkog.io/core-concepts/hybrid-privacy) first.

## 6. P0 — SARIF and JSON flags are placed where the current CLI does not parse them

**Location and exact quote:** [Quickstart — Output Formats](https://docs.inkog.io/getting-started#output-formats): `inkog scan . -output sarif > results.sarif`

**Failure point:** The current Go CLI parses flags before positional arguments. After `scan .`, `-output` can be ignored, leaving default text redirected into a file named `.sarif` or `.json`. That is a silent, dangerous failure in CI.

**Replacement wording:**

> Place flags before the path.  
> **SARIF:** `inkog -output sarif . > results.sarif`  
> **JSON:** `inkog -output json . > results.json`  
> `-output` selects the format; shell redirection selects the filename.

## 7. P0 — Severity syntax and semantics are wrong

**Location and exact quote:** [Quickstart — Filter by Severity](https://docs.inkog.io/getting-started#filter-by-severity): `inkog scan . -severity critical,high`

**Failure point:** The current CLI accepts one minimum threshold, not a comma-separated set. `high` already means CRITICAL + HIGH.

**Replacement wording:**

> To report CRITICAL and HIGH findings, run `inkog -severity high .`. Accepted thresholds are `critical`, `high`, `medium`, and `low`; each includes that level and all more severe levels.

## 8. P1 — The recommended installer is opaque, and Windows is incomplete

**Location and exact quote:** [Installation — Install Script](https://docs.inkog.io/getting-started/installation#install-script-recommended): `curl -fsSL https://inkog.io/install.sh | sh` and “Windows (WSL)”; [Binary Download](https://docs.inkog.io/getting-started/installation#binary-download): `inkog-windows-amd64.exe`.

**Failure point:** The command executes an unpinned remote script without showing the install path, changed shell profile, checksum, or whether a restart is needed. A native Windows `.exe` is listed, but there are no PowerShell, `PATH`, or verification steps; the binary walkthrough is macOS-only.

**Replacement wording:**

> The one-line installer is the convenience path and executes a remote script. For audited environments, download a versioned release and verify its published SHA-256 before adding it to `PATH`. Use separate tested tabs for macOS, Linux, Windows PowerShell, and WSL, including install location, `PATH` change, shell reload, and `inkog -version` verification.

## 9. P0 — Getting Started uses the wrong GitHub Action and omits its required key

**Location and exact quote:** [Installation — GitHub Action](https://docs.inkog.io/getting-started/installation#github-action): `uses: inkog-io/inkog-action@v1`

**Failure point:** The canonical action is `inkog-io/inkog@v1`, and its `api-key` input is required. The example’s `format` and filename inputs also do not match the current action inputs, so lookup or validation can fail before a scan.

**Replacement wording:**

```yaml
permissions:
  contents: read
  security-events: write
  pull-requests: write

steps:
  - uses: actions/checkout@v4
  - uses: inkog-io/inkog@v1
    with:
      api-key: ${{ secrets.INKOG_API_KEY }}
      severity: high
      sarif-upload: true
```

> Create the repository secret `INKOG_API_KEY` first. Do not add a second upload step unless you consume the action’s documented `sarif-file` output.

## 10. P0 — Configuration documents features the current CLI does not expose

**Location and exact quote:** [Configuration — Configuration File](https://docs.inkog.io/getting-started/configuration#configuration-file): `.inkog.yaml`; [Monorepo Configuration](https://docs.inkog.io/getting-started/configuration#monorepo-configuration): `inkog init`

**Failure point:** The current public CLI command reference and source do not expose `init` or a config-file flag, and do not corroborate `.inkog.yaml`, `.inkogignore`, inline suppression, workspaces, rule disabling, or severity overrides. Ignored controls can create false confidence in a security gate.

**Replacement wording:**

> Project configuration files and inline suppression are not available in the current CLI release. Configure scans with the verified flags below.

Remove unsupported examples until they are release-tested. When these features ship, publish a versioned schema, a validation command, and documentation smoke tests generated from the released binary.

## 11. P0 — Environment-variable documentation contradicts itself

**Location and exact quote:** [Configuration — Environment Variables](https://docs.inkog.io/getting-started/configuration#environment-variables): “All configuration options can be set via environment variables.”

**Failure point:** This page shows `INKOG_SEVERITY`, `INKOG_FORMAT`, and `INKOG_IGNORE`; the dedicated environment reference instead lists `INKOG_SERVER_URL`, `INKOG_API_KEY`, `INKOG_OUTPUT_FORMAT`, and `CI`. Unsupported values can be silently ignored in CI.

**Replacement wording:**

> The current CLI reads `INKOG_API_KEY`, `INKOG_SERVER_URL`, and `CI`. Command-line flags take precedence over environment variables, which take precedence over defaults. Not every option has an environment-variable equivalent.

Remove `INKOG_SEVERITY`, `INKOG_FORMAT`, and `INKOG_IGNORE` unless release tests prove that the binary consumes them. Keep the published list generated from, or tested against, each release.

## 12. P0 — GitLab and Jenkins examples use obsolete flags and the wrong report contract

**Location and exact quote:** [Configuration — GitLab CI](https://docs.inkog.io/getting-started/configuration#gitlab-ci): `inkog . --format sarif -o gl-sast-report.json`

**Failure point:** The current CLI uses `-output`, not `--format`/`-o`, and flags come before the path. The example then labels SARIF as GitLab SAST JSON, but GitLab validates SAST against its own schema. Current GitLab uses `artifacts:reports:sarif` for SARIF where that feature is available.

**Replacement wording:**

> Run `inkog -output sarif . > gl-sarif-report.sarif`. On supported GitLab versions and tiers, publish it as `artifacts:reports:sarif`. Otherwise upload it only as a normal artifact or transform it to GitLab’s SAST schema—do not label raw SARIF as `reports:sast`. Store `INKOG_API_KEY` as a masked CI variable.

Jenkins should likewise use `inkog -output json . > results.json`.

## 13. P1 — Email confirmation is account-gated and unverified

**Location and exact quote:** [Dashboard Guide — Sign Up](https://docs.inkog.io/getting-started/dashboard#sign-up): “Confirm your email address.”

**Failure point:** The public signup screen offers GitHub, Google, and email/password, but confirmation behavior cannot be verified without creating an account. The docs do not distinguish OAuth from email signup.

**Replacement wording:**

> Choose one signup method. **Email/password:** create the account, open the confirmation email, and follow its link before opening the Dashboard. **GitHub or Google:** complete provider authorization, then return to Inkog.

After verifying both live paths, add their landing screen, expected redirect, resend action, and recovery guidance for an expired or missing confirmation email.

## 14. P1 — API-key navigation is account-gated and inconsistent

**Location and exact quote:** [Dashboard Guide — API Key](https://docs.inkog.io/getting-started/dashboard#api-key): “API Keys.”

**Failure point:** Quickstart says “dashboard,” Installation says “Dashboard → API Keys,” and Dashboard Guide says avatar → Settings → API Keys. The actual authenticated route cannot be verified without an account.

**Replacement wording:**

> **Account required.** After signing in, open your avatar, choose **Settings**, then **API Keys**. Select **Generate New Key** and copy it immediately; it is shown once.

Add a direct authenticated deep link and screenshot after verifying the live UI.

## 15. P0 — Web Upload contradicts the signed-out product

**Location and exact quote:** [Dashboard Guide — Web Upload](https://docs.inkog.io/getting-started/dashboard#web-upload): “Drag and drop files.”

**Failure point:** The current public product at [app.inkog.io/scan](https://app.inkog.io/scan) has no sidebar or file drop zone; it asks for a public GitHub repository URL. A signed-in upload flow may exist, but it is account-gated and could not be verified.

**Replacement wording:**

> **Scan a public repository without an account:** open `/scan`, paste a public GitHub repository URL, and select **Scan**. The signed-out page does not provide file upload or saved scan policies.

Move file upload into a clearly labeled **Account required** subsection, and publish its navigation only after checking the authenticated controls against the live product.

## 16. P1 — GitHub integration cannot be verified and omits the permission model

**Location and exact quote:** [Dashboard Guide — GitHub Integration](https://docs.inkog.io/getting-started/dashboard#github-integration): “Install the Inkog GitHub App.”

**Failure point:** This requires an Inkog account and GitHub authorization. The guide does not state required scopes, organization-owner approval, what code or data is sent, trigger behavior, or how to revoke access.

**Replacement wording:**

> **Account and GitHub installation permission required.** List the requested scopes, whether an organization owner must approve, how repository selection works, what triggers scans, what data leaves GitHub, and how to disconnect the App.

## 17. P1 — Project management is account-gated

**Location and exact quote:** [Dashboard Guide — Create Project](https://docs.inkog.io/getting-started/dashboard#create-project): “New Project.”

**Failure point:** The control and required fields cannot be verified without Dashboard access; no screenshot, direct link, or empty-state description is provided.

**Replacement wording:**

> **Account required.** From **Projects**, select **New Project**, enter a project name and description, optionally connect a GitHub repository, choose the default scan policy, then select **Create**.

Show the resulting screen and explain how to recover from a duplicate name, inaccessible repository, or failed connection.

## 18. P1 — Exports are account- and scan-gated

**Location and exact quote:** [Dashboard Guide — PDF Report](https://docs.inkog.io/getting-started/dashboard#pdf-report): “Export → PDF.”

**Failure point:** PDF, SARIF, and JSON export controls require a completed scan, so none can be verified as a new signed-out user. Availability by plan is also unstated.

**Replacement wording:**

> Requires at least one completed scan. Open a scan result, select **Export**, then choose PDF, SARIF, or JSON. State plan limits, generated filename and schema, and where the download appears. Add a public sample scan so users can verify the flow without uploading code.

## 19. P1 — Feedback and shortcuts are account- and result-gated

**Location and exact quote:** [Dashboard Guide — Feedback & Calibration](https://docs.inkog.io/getting-started/dashboard#feedback--calibration): “False Positive.”

**Failure point:** These controls and shortcuts require an open finding; they cannot be verified without an account and completed scan. The guide does not say whether feedback changes team or global calibration, or how to undo it.

**Replacement wording:**

> Requires a completed scan. Open a finding, choose **False Positive** or **Confirm**, optionally add a note, and save. State the scope of the feedback, who can see it, and how to reverse it. Provide a sample finding or annotated screenshot for shortcut verification.

## Verification Boundaries

- I did not create an Inkog account, confirm an email, generate an API key, install the GitHub App, connect a repository, upload code, or trigger a scan. Those account and permission gates are reported above as separate findings.
- I did not execute `curl | sh`, npx, or a newly downloaded binary on the host. Command behavior was cross-checked against Inkog’s current public CLI source, npm wrapper documentation, current `action.yml`, dedicated CLI reference, and GitLab’s report documentation.
- The public `/scan` and signup screens were inspected live. Full authenticated Dashboard claims require a disposable test account and test repository for safe verification.

Recommended fix order: canonicalize CLI grammar and API-key behavior → replace or remove stale Configuration material → repair CI and Action examples → clarify privacy and OS setup → add an account-free sample project or annotated Dashboard screenshots.