Cleanup docs and help text

Author: jdalton

README.md

@@ -3,7 +3,7 @@
 [![Socket Badge](https://socket.dev/api/badge/npm/package/socket)](https://socket.dev/npm/package/socket)
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 
-> CLI tool for [Socket.dev]
+CLI for [Socket.dev] security analysis
 
 ## Usage
 
@@ -14,97 +14,78 @@ socket --help
 
 ## Commands
 
-- `socket npm [args...]` and `socket npx [args...]` - Wraps `npm` and `npx` to
-  integrate [Socket.dev] and preempt installation of alerted packages using the
-  builtin resolution of `npm` to precisely determine package installations
+- `socket npm [args...]` and `socket npx [args...]` - Wraps npm/npx with Socket security scanning
 
-- `socket optimize` - Optimize dependencies with
-  [`@socketregistry`](https://github.com/SocketDev/socket-registry) overrides
-  _(👀 [our blog post](https://socket.dev/blog/introducing-socket-optimize))_
+- `socket fix` - Fix CVEs in dependencies
 
-  - `--pin` - Pin overrides to their latest version
-  - `--prod` - Add overrides for only production dependencies
+- `socket optimize` - Optimize dependencies with [`@socketregistry`](https://github.com/SocketDev/socket-registry) overrides
 
-- `socket cdxgen [command]` - Call out to
-  [cdxgen](https://cyclonedx.github.io/cdxgen/#/?id=getting-started). See
-  [their documentation](https://cyclonedx.github.io/cdxgen/#/CLI?id=getting-help)
-  for commands.
+- `socket cdxgen [command]` - Run [cdxgen](https://cyclonedx.github.io/cdxgen/#/?id=getting-started) for SBOM generation
 
 ## Aliases
 
 All aliases support the flags and arguments of the commands they alias.
 
-- `socket ci` - alias for `socket scan create --report` which creates a report for the current directory and quits with an exit code if the result is unhealthy
+- `socket ci` - Alias for `socket scan create --report` (creates report and exits with error if unhealthy)
 
 ## Flags
 
 ### Output flags
 
-- `--json` - Outputs result as JSON which can be piped into [`jq`](https://stedolan.github.io/jq/) and other tools
-- `--markdown` - Outputs result as Markdown which can be copied into issues, pull requests, or chats
+- `--json` - Output as JSON
+- `--markdown` - Output as Markdown
 
 ### Other flags
 
-- `--dry-run` - Run a command without uploading anything
-- `--debug` - Output additional debug
-- `--help` - Prints help documentation
-- `--max-old-space-size` - Set Node's V8 [`--max-old-space-size`](https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-mib) option
-- `--max-semi-space-size` - Set Node's V8 [`--max-semi-space-size`](https://nodejs.org/api/cli.html#--max-semi-space-sizesize-in-mib) option
-- `--version` - Prints the Socket CLI version
+- `--dry-run` - Run without uploading
+- `--debug` - Show debug output
+- `--help` - Show help
+- `--max-old-space-size` - Set Node.js memory limit
+- `--max-semi-space-size` - Set Node.js heap size
+- `--version` - Show version
 
 ## Configuration files
 
-Socket CLI reads and uses data from a
-[`socket.yml` file](https://docs.socket.dev/docs/socket-yml) in the folder you
-run it in. It supports the version 2 of the `socket.yml` file format and makes
-use of the `projectIgnorePaths` to excludes files when creating a report.
+Socket CLI reads [`socket.yml`](https://docs.socket.dev/docs/socket-yml) configuration files.
+Supports version 2 format with `projectIgnorePaths` for excluding files from reports.
 
 ## Environment variables
 
-- `SOCKET_CLI_API_TOKEN` - Set the Socket API token
-- `SOCKET_CLI_CONFIG` - A JSON stringified Socket configuration object
-- `SOCKET_CLI_GITHUB_API_URL` - Change the base URL for GitHub REST API calls
-- `SOCKET_CLI_GIT_USER_EMAIL` - The git config `user.email` used by Socket CLI<br>
-  *Defaults:* `github-actions[bot]@users.noreply.github.com`<br>
-- `SOCKET_CLI_GIT_USER_NAME` - The git config `user.name` used by Socket CLI<br>
-  *Defaults:* `github-actions[bot]`<br>
-- `SOCKET_CLI_GITHUB_TOKEN` - A classic or fine-grained [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with the "repo" scope or read/write permissions set for "Contents" and "Pull Request"<br>
-  *Aliases:* `GITHUB_TOKEN`<br>
-- `SOCKET_CLI_NO_API_TOKEN` - Make the default API token `undefined`
-- `SOCKET_CLI_NPM_PATH` - The absolute location of the npm directory
-- `SOCKET_CLI_ORG_SLUG` - Specify the Socket organization slug<br><br>
-- `SOCKET_CLI_ACCEPT_RISKS` - Accept risks of a Socket wrapped npm/npx run
-- `SOCKET_CLI_VIEW_ALL_RISKS` - View all risks of a Socket wrapped npm/npx run
+- `SOCKET_CLI_API_TOKEN` - Socket API token
+- `SOCKET_CLI_CONFIG` - JSON configuration object
+- `SOCKET_CLI_GITHUB_API_URL` - GitHub API base URL
+- `SOCKET_CLI_GIT_USER_EMAIL` - Git user email (default: `github-actions[bot]@users.noreply.github.com`)
+- `SOCKET_CLI_GIT_USER_NAME` - Git user name (default: `github-actions[bot]`)
+- `SOCKET_CLI_GITHUB_TOKEN` - GitHub token with repo access (alias: `GITHUB_TOKEN`)
+- `SOCKET_CLI_NO_API_TOKEN` - Disable default API token
+- `SOCKET_CLI_NPM_PATH` - Path to npm directory
+- `SOCKET_CLI_ORG_SLUG` - Socket organization slug
+- `SOCKET_CLI_ACCEPT_RISKS` - Accept npm/npx risks
+- `SOCKET_CLI_VIEW_ALL_RISKS` - Show all npm/npx risks
 
 ## Contributing
 
-### Setup
-
-To run locally execute the following commands:
+Run locally:
 
 ```
 npm install
 npm run build
 npm exec socket
 ```
 
-### Environment variables for development
+### Development environment variables
 
-- `SOCKET_CLI_API_BASE_URL` - Change the base URL for Socket API calls<br>
-  *Defaults:* The "apiBaseUrl" value of socket/settings local app data if present, else `https://api.socket.dev/v0/`<br>
-- `SOCKET_CLI_API_PROXY` - Set the proxy Socket API requests are routed through, e.g. if set to<br>
-  [`http://127.0.0.1:9090`](https://docs.proxyman.io/troubleshooting/couldnt-see-any-requests-from-3rd-party-network-libraries), then all request are passed through that proxy<br>
-  *Aliases:* `HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY`, and `http_proxy`<br>
-- `SOCKET_CLI_API_TIMEOUT` - Set the timeout in milliseconds for Socket API requests
-- `SOCKET_CLI_DEBUG` - Enable debug logging in Socket CLI
-- `DEBUG` - Enable debug logging based on the [`debug`](https://socket.dev/npm/package/debug) package
+- `SOCKET_CLI_API_BASE_URL` - API base URL (default: `https://api.socket.dev/v0/`)
+- `SOCKET_CLI_API_PROXY` - Proxy for API requests (aliases: `HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY`, `http_proxy`)
+- `SOCKET_CLI_API_TIMEOUT` - API request timeout in milliseconds
+- `SOCKET_CLI_DEBUG` - Enable debug logging
+- `DEBUG` - Enable [`debug`](https://socket.dev/npm/package/debug) package logging
 
 ## See also
 
-- [Announcement blog post](https://socket.dev/blog/announcing-socket-cli-preview)
-- [Socket API Reference](https://docs.socket.dev/reference) - The API used by Socket CLI
-- [Socket GitHub App](https://github.com/apps/socket-security) - The plug-and-play GitHub App
-- [`@socketsecurity/sdk`](https://github.com/SocketDev/socket-sdk-js) - The SDK used by Socket CLI
+- [Socket API Reference](https://docs.socket.dev/reference)
+- [Socket GitHub App](https://github.com/apps/socket-security)
+- [`@socketsecurity/sdk`](https://github.com/SocketDev/socket-sdk-js)
 
 [Socket.dev]: https://socket.dev/
 

src/commands/analytics/cmd-analytics.test.mts

@@ -35,8 +35,8 @@ describe('socket analytics', async () => {
 
           Options
             --file              Path to store result, only valid with --json/--markdown
-            --json              Output result as json
-            --markdown          Output result as markdown
+            --json              Output as JSON
+            --markdown          Output as Markdown
 
           Examples
             $ socket analytics org 7

src/commands/audit-log/cmd-audit-log.test.mts

@@ -45,8 +45,8 @@ describe('socket audit-log', async () => {
           Options
             --interactive       Allow for interactive elements, asking for input.
                                 Use --no-interactive to prevent any input questions, defaulting them to cancel/no.
-            --json              Output result as json
-            --markdown          Output result as markdown
+            --json              Output as JSON
+            --markdown          Output as Markdown
             --org               Force override the organization slug, overrides the default org from config
             --page              Result page to fetch
             --per-page          Results per page - default is 30

src/commands/ci/cmd-ci.mts

@@ -13,7 +13,8 @@ import type {
 
 const config: CliCommandConfig = {
   commandName: 'ci',
-  description: 'Shorthand for `socket scan create --report --no-interactive`',
+  description:
+    'Alias for `socket scan create --report` (creates report and exits with error if unhealthy)',
   hidden: false,
   flags: {
     ...commonFlags,

src/commands/ci/cmd-ci.test.mts

@@ -17,7 +17,7 @@ describe('socket ci', async () => {
       const { code, stderr, stdout } = await spawnSocketCli(binCliPath, cmd)
       expect(stdout).toMatchInlineSnapshot(
         `
-        "Shorthand for \`socket scan create --report --no-interactive\`
+        "Alias for \`socket scan create --report\` (creates report and exits with error if unhealthy)
 
           Usage
             $ socket ci [options]

src/commands/cli.test.mts

@@ -30,7 +30,10 @@ describe('socket root command', async () => {
             socket login                Setup Socket CLI with an API token and defaults
             socket scan create          Create a new Socket scan and report
             socket npm/lodash@4.17.21   Request the Socket score of a package
-            socket ci                   Shorthand for \`socket scan create --report --no-interactive\`
+            socket fix                  Fix CVEs in dependencies
+            socket optimize             Optimize dependencies with @socketregistry overrides
+            socket cdxgen               Run cdxgen for SBOM generation
+            socket ci                   Alias for \`socket scan create --report\` (creates report and exits with error if unhealthy)
 
           Socket API
             analytics                   Look up analytics data
@@ -42,11 +45,9 @@ describe('socket root command', async () => {
             threat-feed                 [Beta] View the threat-feed
 
           Local tools
-            fix                         Update dependencies with "fixable" Socket alerts
             manifest                    Generate a dependency manifest for certain ecosystems
-            npm                         Run npm with the Socket wrapper
-            npx                         Run npx with the Socket wrapper
-            optimize                    Optimize dependencies with @socketregistry overrides
+            npm                         Wraps npm with Socket security scanning
+            npx                         Wraps npx with Socket security scanning
             raw-npm                     Run npm without the Socket wrapper
             raw-npx                     Run npx without the Socket wrapper
 
@@ -63,9 +64,9 @@ describe('socket root command', async () => {
 
             --compact-header            Use compact single-line header format (auto-enabled in CI)
             --config                    Override the local config with this JSON
-            --dry-run                   Do input validation for a command and exit 0 when input is ok
-            --help                      Print this help
-            --help-full                 Print full help including environment variables
+            --dry-run                   Run without uploading
+            --help                      Show help
+            --help-full                 Show full help including environment variables
             --no-banner                 Hide the Socket banner
             --no-spinner                Hide the console spinner
             --version                   Print the app version

src/commands/config/cmd-config-auto.test.mts

@@ -23,8 +23,8 @@ describe('socket config auto', async () => {
             $ socket config auto [options] KEY
 
           Options
-            --json              Output result as json
-            --markdown          Output result as markdown
+            --json              Output as JSON
+            --markdown          Output as Markdown
 
           Attempt to automatically discover the correct value for a given config KEY.
 

src/commands/config/cmd-config-get.test.mts

@@ -27,8 +27,8 @@ describe('socket config get', async () => {
           config then the value will come from that override.
 
           Options
-            --json              Output result as json
-            --markdown          Output result as markdown
+            --json              Output as JSON
+            --markdown          Output as Markdown
 
           KEY is an enum. Valid keys:
 

src/commands/config/cmd-config-list.test.mts

@@ -26,8 +26,8 @@ describe('socket config get', async () => {
 
           Options
             --full              Show full tokens in plaintext (unsafe)
-            --json              Output result as json
-            --markdown          Output result as markdown
+            --json              Output as JSON
+            --markdown          Output as Markdown
 
           Examples
             $ socket config list"

src/commands/config/cmd-config-set.test.mts

@@ -25,8 +25,8 @@ describe('socket config get', async () => {
             $ socket config set [options] <KEY> <VALUE>
 
           Options
-            --json              Output result as json
-            --markdown          Output result as markdown
+            --json              Output as JSON
+            --markdown          Output as Markdown
 
           This is a crude way of updating the local configuration for this CLI tool.