INS-28 docs: update README with npx usage, skills, analytics, OSS linking#56
Merged
INS-28 docs: update README with npx usage, skills, analytics, OSS linking#56
Conversation
- Drop global install; recommend npx @insforge/cli - Document OSS/self-hosted link via --api-base-url + --api-key - Add Agent Skills section explaining auto-installed skills - Add Analytics section documenting default PostHog reporting Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
WalkthroughThe PR updates CLI documentation to recommend npx-based invocations over global installs, introduces new Agent Skills and Analytics documentation sections, and adds comprehensive development guidelines and skill definitions for CLI development workflows. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
README.md (1)
602-609: Clarify that global linking is contributor-only.Earlier sections recommend
npxand no global install, but Development usesnpm link(valid for local contributor workflows). A one-line clarification would prevent mixed messaging.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 602 - 609, The README currently suggests `npm link` in the Development steps which conflicts with earlier guidance to use `npx` and avoid global installs; update the Development block (the lines showing `npm link` / `npm run dev`) to add a single clarifying sentence stating that `npm link` is intended only for local contributors/maintainers (not for general users) and that regular users should use `npx insforge` or install via npm/yarn as described earlier; reference the `npm link` and `npx` commands so the clarification appears directly beside the `npm link` instruction.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Line 556: The README's phrase "build time" is incorrect because the code reads
POSTHOG_API_KEY from the environment at runtime; update the sentence that
currently claims "If you build the CLI from source without setting
`POSTHOG_API_KEY` at build time, analytics become a no-op automatically" to
state that analytics are disabled only when `POSTHOG_API_KEY` is not present in
the runtime environment (or when explicitly unset/disabled at runtime), and
clarify that building without the variable does not guarantee disabled telemetry
unless the runtime env lacks `POSTHOG_API_KEY`; mention the `POSTHOG_API_KEY`
env variable explicitly in the rewording.
- Around line 115-121: Update the README wording around the npx `@insforge/cli`
link example to clarify that --api-base-url accepts any valid URL (not only the
https://{app_key}.{region}.insforge.app pattern); mention that the CLI will skip
OAuth and write credentials to .insforge/project.json when linking with
--api-key, and add examples/notes that custom domains, localhost, or
non-{app_key}.{region} hostnames are supported by the link command
(--api-base-url and --api-key).
---
Nitpick comments:
In `@README.md`:
- Around line 602-609: The README currently suggests `npm link` in the
Development steps which conflicts with earlier guidance to use `npx` and avoid
global installs; update the Development block (the lines showing `npm link` /
`npm run dev`) to add a single clarifying sentence stating that `npm link` is
intended only for local contributors/maintainers (not for general users) and
that regular users should use `npx insforge` or install via npm/yarn as
described earlier; reference the `npm link` and `npx` commands so the
clarification appears directly beside the `npm link` instruction.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Comment on lines
+115
to
+121
| # OSS / self-hosted: link via host URL + API key (no platform login required) | ||
| npx @insforge/cli link \ | ||
| --api-base-url https://<app-key>.<region>.insforge.app \ | ||
| --api-key <your-project-api-key> | ||
| ``` | ||
|
|
||
| #### `insforge current` | ||
| For OSS or self-hosted deployments, you can link directly using the host URL and API key — the CLI skips the platform OAuth flow and writes the credentials straight into `.insforge/project.json`. The host URL format is `https://{app_key}.{region}.insforge.app` (e.g. `https://uhzx8md3.us-east.insforge.app`). |
There was a problem hiding this comment.
Broaden self-hosted URL guidance to match actual CLI behavior.
The docs currently imply self-hosted links must use https://{app_key}.{region}.insforge.app, but link accepts any valid URL for --api-base-url. This can mislead custom-domain/self-hosted users.
Suggested doc tweak
-# OSS / self-hosted: link via host URL + API key (no platform login required)
+# OSS / self-hosted: link via API base URL + API key (no platform login required)
npx `@insforge/cli` link \
- --api-base-url https://<app-key>.<region>.insforge.app \
+ --api-base-url https://<your-host> \
--api-key <your-project-api-key>
-For OSS or self-hosted deployments, you can link directly using the host URL and API key — the CLI skips the platform OAuth flow and writes the credentials straight into `.insforge/project.json`. The host URL format is `https://{app_key}.{region}.insforge.app` (e.g. `https://uhzx8md3.us-east.insforge.app`).
+For OSS or self-hosted deployments, you can link directly using an API base URL and API key — the CLI skips the platform OAuth flow and writes the credentials straight into `.insforge/project.json`.
+For InsForge-hosted instances, the URL is typically `https://{app_key}.{region}.insforge.app` (e.g. `https://uhzx8md3.us-east.insforge.app`).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| # OSS / self-hosted: link via host URL + API key (no platform login required) | |
| npx @insforge/cli link \ | |
| --api-base-url https://<app-key>.<region>.insforge.app \ | |
| --api-key <your-project-api-key> | |
| ``` | |
| #### `insforge current` | |
| For OSS or self-hosted deployments, you can link directly using the host URL and API key — the CLI skips the platform OAuth flow and writes the credentials straight into `.insforge/project.json`. The host URL format is `https://{app_key}.{region}.insforge.app` (e.g. `https://uhzx8md3.us-east.insforge.app`). | |
| # OSS / self-hosted: link via API base URL + API key (no platform login required) | |
| npx `@insforge/cli` link \ | |
| --api-base-url https://<your-host> \ | |
| --api-key <your-project-api-key> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 115 - 121, Update the README wording around the npx
`@insforge/cli` link example to clarify that --api-base-url accepts any valid URL
(not only the https://{app_key}.{region}.insforge.app pattern); mention that the
CLI will skip OAuth and write credentials to .insforge/project.json when linking
with --api-key, and add examples/notes that custom domains, localhost, or
non-{app_key}.{region} hostnames are supported by the link command
(--api-base-url and --api-key).
|
|
||
| The CLI reports anonymous usage events to [PostHog](https://posthog.com) so we can understand which features are being used and prioritize improvements. | ||
|
|
||
| Analytics are enabled by default in the published npm package. If you build the CLI from source without setting `POSTHOG_API_KEY` at build time, analytics become a no-op automatically. |
There was a problem hiding this comment.
“Build time” wording for analytics appears inaccurate.
The no-op behavior is described as build-time, but implementation reads POSTHOG_API_KEY from env in runtime code path. Please reword to avoid privacy/telemetry confusion.
Suggested doc tweak
-Analytics are enabled by default in the published npm package. If you build the CLI from source without setting `POSTHOG_API_KEY` at build time, analytics become a no-op automatically.
+Analytics are enabled by default in the published npm package. If `POSTHOG_API_KEY` is not set in the runtime environment, analytics become a no-op automatically.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Analytics are enabled by default in the published npm package. If you build the CLI from source without setting `POSTHOG_API_KEY` at build time, analytics become a no-op automatically. | |
| Analytics are enabled by default in the published npm package. If `POSTHOG_API_KEY` is not set in the runtime environment, analytics become a no-op automatically. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 556, The README's phrase "build time" is incorrect because
the code reads POSTHOG_API_KEY from the environment at runtime; update the
sentence that currently claims "If you build the CLI from source without setting
`POSTHOG_API_KEY` at build time, analytics become a no-op automatically" to
state that analytics are disabled only when `POSTHOG_API_KEY` is not present in
the runtime environment (or when explicitly unset/disabled at runtime), and
clarify that building without the variable does not guarantee disabled telemetry
unless the runtime env lacks `POSTHOG_API_KEY`; mention the `POSTHOG_API_KEY`
env variable explicitly in the rewording.
Contributor
|
this only updates readme instead of skills? |
Member
Author
|
https://linear.app/insforge/issue/INS-28/update-cli-readme-for-usage-and-skills |
Contributor
|
linear created this.. when i saw add skills i mean having a skill for this repo... so ai can understand we need tracking methods and testing |
Covers existing-pattern conventions, PostHog analytics usage, agent-skills sync, and the tag-triggered npm release workflow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jwfing
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Line 89: The link in CLAUDE.md currently points to a relative path
'../../../.github/workflows/publish.yml' which will break from the repo root;
update the link to a repo-root-relative path (for example
'/.github/workflows/publish.yml') so GitHub resolves it correctly—locate the
string '../../../.github/workflows/publish.yml' in CLAUDE.md and replace it with
'/.github/workflows/publish.yml'.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
can we make this to claude and codex skills? |
AGENTS.md is the cross-agent convention supported by Claude Code, Codex, Cursor, Aider, and others. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Member
Author
|
@tonychang04 fixed. |
Rename AGENTS.md to DEVELOPMENT.md as the canonical dev guide, then add lightweight cli-development skill stubs under .agents/skills/ (Codex) and .claude/skills/ (Claude Code) that both reference DEVELOPMENT.md. Force-added since .agents and .claude are gitignored for installSkills() artifacts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
tonychang04
approved these changes
Apr 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
🤖 Generated with Claude Code
Note
Update README to use
npx @insforge/cliand add development guide with analytics and skills docsnpx @insforge/cliinstead of a globally installedinsforgebinary.--api-base-urland--api-key, and expands sections covering Agent Skills and Analytics.cli-developmentskill definition into both .agents/skills/ and .claude/skills/ pointing to DEVELOPMENT.md.Macroscope summarized d7332f4.
Summary by CodeRabbit
Documentation
npxinstead of global package installationNew Features