Go Modules Reference

CLI Commands

go list -m (primary lookup)

# Latest version of a module
go list -m golang.org/x/sync@latest
# Output: golang.org/x/sync v0.12.0

# All available versions
go list -m -versions golang.org/x/sync
# Output: golang.org/x/sync v0.0.0-20181108010431-42b317875d0f v0.1.0 v0.2.0 ...

# JSON output with more detail
go list -m -json golang.org/x/sync@latest
# {"Path": "golang.org/x/sync", "Version": "v0.12.0", "Time": "2025-01-..."}

Gotcha: go list -m must be run inside a Go module directory (one containing go.mod). Outside a module, use GOFLAGS=-mod=mod or the Go proxy API instead.

go get vs go install

These two commands serve different purposes:

# go get: add/update a dependency in go.mod (for libraries)
go get github.com/gin-gonic/gin@latest
go get github.com/gin-gonic/gin@v1.10.0

# go install: install a binary tool (for executables)
go install golang.org/x/tools/gopls@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

• Use go get when adding a library dependency to your project
• Use go install when installing a standalone CLI tool
• Since Go 1.17, go get no longer builds and installs binaries - use go install for that

go mod tidy

# Clean up go.mod and go.sum
go mod tidy

# Add missing and remove unused dependencies
# Also downloads missing modules

Go Module Proxy API

Base URL: https://proxy.golang.org

Get latest version

# Latest version info
curl -s https://proxy.golang.org/golang.org/x/sync/@latest
# {"Version":"v0.12.0","Time":"2025-01-06T15:10:07Z"}

# List all versions
curl -s https://proxy.golang.org/golang.org/x/sync/@v/list
# v0.0.0-20181108010431-42b317875d0f
# v0.1.0
# v0.2.0
# ...

# Get go.mod for a specific version
curl -s https://proxy.golang.org/golang.org/x/sync/@v/v0.12.0.mod

Case-encoding in proxy URLs

Go module paths are case-sensitive. The proxy uses a special encoding where uppercase letters become ! + lowercase:

# github.com/Azure/azure-sdk-for-go -> github.com/!azure/azure-sdk-for-go
curl -s https://proxy.golang.org/github.com/'!azure'/azure-sdk-for-go/@latest

This rarely comes up for most packages but is critical for Microsoft, Google, and other mixed-case module paths.

Module Paths and Versioning

Module path structure

github.com/user/repo                    # Standard module
github.com/user/repo/v2                 # Major version 2+
golang.org/x/tools                      # Go standard library extensions
google.golang.org/grpc                  # Vanity import path

Major version suffixes

Go modules use major version suffixes in the import path for v2+:

import "github.com/user/repo"       // v0.x or v1.x
import "github.com/user/repo/v2"    // v2.x
import "github.com/user/repo/v3"    // v3.x

# Get latest v1
go list -m github.com/user/repo@latest

# Get latest v2 (different module path!)
go list -m github.com/user/repo/v2@latest

Gotcha: v0 and v1 do not have a version suffix in the import path. Starting from v2, the suffix is required. If you go get repo/v2 but the module hasn't published a v2, it fails.

Version selection

# Specific version
go get github.com/gin-gonic/gin@v1.10.0

# Latest tagged version
go get github.com/gin-gonic/gin@latest

# Specific commit (pseudo-version)
go get github.com/gin-gonic/gin@abc1234

# Upgrade all dependencies
go get -u ./...

# Upgrade only patch versions
go get -u=patch ./...

go.mod File Format

module github.com/myorg/myproject

go 1.22

require (
    github.com/gin-gonic/gin v1.10.0
    golang.org/x/sync v0.12.0
)

// Indirect dependencies (transitive)
require (
    github.com/some/indirect v1.0.0 // indirect
)

// Replace directives (local development or forks)
replace github.com/original/pkg => ../local-fork

// Exclude a broken version
exclude github.com/broken/pkg v1.0.1

Common Gotchas

1. Module paths are case-sensitive - github.com/User/Repo and github.com/user/repo are different modules. Always use the exact casing from the repository.

2. go get in module mode requires go.mod - Running go get outside a module directory with GO111MODULE=on (default since Go 1.16) fails. Initialize with go mod init first.

3. Major version suffixes change the import path - v2+ of a module is a completely different module path. You cannot go get repo@v2.0.0 - you must go get repo/v2@v2.0.0.

4. @latest may not be the newest tag - @latest resolves to the latest stable (non-pre-release) semver tag. A v2.0.0-beta.1 tag won't be selected by @latest. Use @v2.0.0-beta.1 explicitly for pre-releases.

5. Private modules bypass the proxy - Modules from private repos aren't available on proxy.golang.org. Set GONOSUMCHECK and GOPRIVATE for private module paths:

   go env -w GOPRIVATE=github.com/myorg/*

6. go mod tidy may upgrade dependencies - Running go mod tidy can change versions in go.sum if the dependency graph has changed. Review the diff before committing.

7. Retracted versions - Module authors can retract versions via go.mod. A retracted version won't be selected by @latest but can still be explicitly requested.

npm Registry Reference

CLI Commands

npm view (primary lookup)

# Latest version
npm view express version
# Output: 4.21.2

# All published versions as JSON array
npm view express versions --json

# Specific metadata fields
npm view express description homepage license

# Check dist-tags (latest, next, canary, etc.)
npm view express dist-tags --json

# Peer dependencies (critical for plugin ecosystems)
npm view eslint-plugin-react peerDependencies --json

# Check engines field (minimum Node.js version)
npm view express engines --json

# Time of publication for each version
npm view express time --json

npm info (alias)

npm info is an alias for npm view. Both work identically.

npm search

# Search for packages by keyword
npm search express --json | jq '.[0:5]'

# Search with specific fields
npm search --long express

npx vs npm install

• npx <pkg> - Downloads and runs a package without installing it globally. Use for one-off CLI tools like create-react-app, prettier, or eslint.
• npm install <pkg> - Installs into node_modules/ as a project dependency.
• npm install -g <pkg> - Installs globally. Prefer npx over global installs for most CLI tools.

Registry API

Base URL: https://registry.npmjs.org

Get package metadata

# Full metadata (large response)
curl -s https://registry.npmjs.org/express | jq '.["dist-tags"].latest'

# Abbreviated metadata (faster, less data)
curl -s -H "Accept: application/vnd.npm.install-v1+json" \
  https://registry.npmjs.org/express | jq '.["dist-tags"].latest'

# Specific version
curl -s https://registry.npmjs.org/express/4.21.2 | jq '.version'

# Latest tag shortcut
curl -s https://registry.npmjs.org/express/latest | jq '.version'

Scoped packages

Scoped packages (e.g. @scope/name) require URL encoding of the /:

# @babel/core -> @babel%2fcore
curl -s https://registry.npmjs.org/@babel%2fcore/latest | jq '.version'

# @types/react -> @types%2freact
curl -s https://registry.npmjs.org/@types%2freact/latest | jq '.version'

The CLI handles this automatically - npm view @babel/core version works without encoding.

Version Ranges and Semver

npm uses node-semver for version resolution:

Check what a range resolves to

# What's the latest version matching ^17?
npm view react@'^17' version
# Returns the latest 17.x

# What versions match a range?
npm view react versions --json | jq '[.[] | select(startswith("18."))]'

Lockfiles

• package-lock.json - npm's lockfile (npm 5+). Pins exact versions for reproducible installs.
• npm ci - Clean install from lockfile only. Fails if package.json and lockfile are out of sync. Use in CI.
• npm install - Updates lockfile if package.json changed. Use in development.

Peer Dependencies

Peer dependencies declare compatibility requirements without installing the dependency:

# Check what peers a package requires
npm view eslint-plugin-react peerDependencies --json
# {"eslint": "^3 || ^4 || ^5 || ^6 || ^7 || ^8 || ^9"}

# npm 7+ auto-installs peer deps (npm 3-6 did not)
# This can cause version conflicts - check before installing

Common Gotchas

1. npm view requires the package to exist - If the package name is wrong, you get an E404. Use this as an existence check.

2. Scoped packages in API URLs need encoding - @scope/name becomes @scope%2fname in URLs. The CLI handles this transparently.

3. npm view shows the latest dist-tag by default - Some packages publish newer versions under different tags (e.g. next, canary, rc). Check dist-tags if the user wants a pre-release.

4. npm outdated requires a project - Only works inside a directory with package.json. Use npm view for ad-hoc version checks.

5. Private packages return 404 or 401 - If a package lookup fails with auth errors, it may be a private package requiring .npmrc configuration. This is out of scope for this skill.

6. Deprecated packages - npm view <pkg> shows a deprecation notice if the package is deprecated. Always check for this and warn the user.

# Check if deprecated
npm view request deprecated
# Output: "request has been deprecated..."

Python Registry Reference

CLI Commands

pip index versions (primary lookup)

# List all available versions (requires pip 21.2+)
pip index versions numpy
# Output:
# numpy (2.2.3)
# Available versions: 2.2.3, 2.2.2, 2.2.1, ...
# INSTALLED: 1.26.4
# LATEST:    2.2.3

# Filter by Python version compatibility
pip index versions numpy --python-version 3.9

Gotcha: pip index versions was added in pip 21.2. On older versions, this command does not exist. Check pip version with pip --version and fall back to the PyPI API.

pip vs pip3 vs python -m pip

# Recommended: always use python -m pip to ensure correct Python
python -m pip install numpy
python3 -m pip install numpy

# Direct pip command (may point to wrong Python)
pip install numpy      # Could be Python 2 on some systems
pip3 install numpy     # Usually Python 3, but not guaranteed

# Check which Python pip points to
pip --version
# pip 24.0 from /usr/lib/python3.12/site-packages/pip (python 3.12)

pip show (installed package info)

# Check installed version and metadata
pip show numpy
# Name: numpy
# Version: 1.26.4
# Requires-Python: >=3.9
# ...

pip install with version constraints

# Exact version
pip install django==4.2.20

# Minimum version
pip install django>=4.2

# Version range
pip install 'django>=4.2,<5.0'

# Latest compatible (equivalent to npm's ^)
pip install 'django~=4.2'    # >=4.2, <5.0

# Upgrade to latest
pip install --upgrade django

PyPI JSON API

Base URL: https://pypi.org

Get package metadata

# Full metadata (all versions)
curl -s https://pypi.org/pypi/numpy/json | jq '.info.version'

# Specific version
curl -s https://pypi.org/pypi/numpy/2.2.3/json | jq '.info.version'

# Python version requirement
curl -s https://pypi.org/pypi/django/json | jq '.info.requires_python'
# Output: ">=3.10"

# All available versions
curl -s https://pypi.org/pypi/numpy/json | jq '.releases | keys[]' | tail -10

# Package description and homepage
curl -s https://pypi.org/pypi/numpy/json | jq '{summary: .info.summary, home: .info.home_page}'

Check package existence

# Returns 200 if exists, 404 if not
curl -s -o /dev/null -w "%{http_code}" https://pypi.org/pypi/some-package-name/json

Virtual Environments

Always recommend virtual environments for Python projects:

# Create a venv
python -m venv .venv

# Activate (bash/zsh)
source .venv/bin/activate

# Activate (fish)
source .venv/bin/activate.fish

# Activate (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Install into the venv
pip install numpy

# Deactivate
deactivate

Gotcha: Running pip install without an active virtual environment installs globally (or into the user site-packages with --user). Always check for an active venv before suggesting installs. Look for (.venv) in the shell prompt or check sys.prefix.

PEP 440 Version Specifiers

requirements.txt format

numpy>=1.26,<3.0
django~=4.2
requests==2.32.3
python-dateutil>=2.8

pyproject.toml format (modern)

[project]
dependencies = [
    "numpy>=1.26,<3.0",
    "django~=4.2",
    "requests>=2.32",
]

Common Gotchas

1. pip index versions requires pip 21.2+ - Falls back silently to nothing on older versions. Always check pip version first or use the PyPI API.

2. Package name normalization - PyPI treats -, _, and . as equivalent in package names. python-dateutil, python_dateutil, and python.dateutil all resolve to the same package. Use the canonical name (hyphens) in install commands.

3. Typosquatting - PyPI has had malicious packages with names similar to popular ones (e.g. python-dateutil vs dateutil). Always verify the exact package name.

4. requires_python field - Check this before recommending a package version. A user on Python 3.8 cannot install Django 5.x (requires Python 3.10+).

5. System Python vs user Python - On macOS and many Linux distros, python or python3 is the system Python. Installing packages into it can break system tools. Always use a virtual environment.

6. pip resolver conflicts - pip 20.3+ has a strict dependency resolver. If install fails with resolver errors, the user may need to relax version constraints or use --no-deps (with caution).

7. Extras/optional dependencies - Some packages have optional feature groups:

   pip install fastapi[standard]   # Includes uvicorn, httptools, etc.
   pip install pandas[excel]       # Includes openpyxl for Excel support

Ruby Gems Reference

CLI Commands

gem search (primary lookup)

# Search for exact gem name (use anchors for exact match)
gem search ^rails$ --remote
# Output: rails (8.0.2)

# Without anchors, matches partial names (returns many results)
gem search rails --remote | head -5
# Output:
# rails (8.0.2)
# rails-admin (0.0.1)
# rails-api (0.4.1)
# ...

Gotcha: Always use ^name$ regex anchors for exact matches. gem search rails without anchors returns dozens of gems with "rails" anywhere in the name.

gem info

# Detailed info about a gem
gem info rails --remote
# Output includes: version, authors, homepage, license, dependencies

# List all remote versions
gem list rails --remote --all | head -5
# rails (8.0.2, 8.0.1, 8.0.0, 7.2.2.1, ...)

gem install

# Install latest version
gem install rails

# Install specific version
gem install rails -v 7.2.2.1

# Install with version constraint
gem install rails -v '~> 7.2'

# Install without docs (faster)
gem install rails --no-document

# Install into a specific directory
gem install rails --install-dir ./vendor/gems

gem specification

# Get detailed spec info in YAML
gem specification rails --remote

# Get specific field
gem specification rails --remote --field version
# Output: 8.0.2

# Get dependencies
gem specification rails --remote --field dependencies

RubyGems.org API

Base URL: https://rubygems.org

Get gem metadata

# Get gem info as JSON
curl -s https://rubygems.org/api/v1/gems/rails.json | jq '.version'
# Output: "8.0.2"

# Get all versions
curl -s https://rubygems.org/api/v1/versions/rails.json | jq '.[0:5] | .[].number'

# Get dependencies for a specific version
curl -s https://rubygems.org/api/v1/versions/rails/latest.json | jq '.version'

# Search for gems
curl -s 'https://rubygems.org/api/v1/search.json?query=rails&page=1' | jq '.[0:3] | .[].name'

# Get download count
curl -s https://rubygems.org/api/v1/gems/rails.json | jq '.downloads'

Check gem existence

# Returns 200 if exists, 404 if not
curl -s -o /dev/null -w "%{http_code}" https://rubygems.org/api/v1/gems/some-gem-name.json

Bundler vs gem install

When to use which

• gem install <name> - Install a standalone tool or global gem (e.g. rails, rubocop)
• bundle add <name> - Add a dependency to a project's Gemfile and install it
• bundle install - Install all dependencies from Gemfile.lock
• bundle exec <cmd> - Run a command using the project's bundled gems

Gemfile format

source 'https://rubygems.org'

# Latest version
gem 'rails'

# Specific version
gem 'rails', '8.0.2'

# Version constraints
gem 'rails', '~> 7.2'        # >= 7.2, < 8.0
gem 'rails', '>= 7.0', '< 9'

# Development only
gem 'rspec', group: :development
gem 'rubocop', group: [:development, :test]

# GitHub source
gem 'my-gem', git: 'https://github.com/user/repo'

# Platform-specific
gem 'sqlite3', platforms: [:ruby, :mswin]

bundle add

# Add to Gemfile and install
bundle add rails

# Add specific version
bundle add rails --version "~> 7.2"

# Add to a group
bundle add rspec --group development

# Skip install (just modify Gemfile)
bundle add rails --skip-install

Version Constraints

Ruby gems use these version constraint operators:

The pessimistic operator (~>) is the most common. It's similar to npm's ^ for major versions and ~ for patch versions.

Platform Gems

Some gems have platform-specific variants (e.g. native extensions):

# Check available platforms for a gem
curl -s https://rubygems.org/api/v1/versions/nokogiri.json | \
  jq '[.[0:5] | .[] | {number, platform}]'

# Common platforms:
# ruby       - Pure Ruby (works everywhere)
# java       - JRuby
# x86_64-linux
# x86_64-darwin
# arm64-darwin
# x64-mingw-ucrt (Windows)

Bundler automatically selects the correct platform variant. When specifying versions manually, be aware that platform-specific gems may have different available versions.

Common Gotchas

1. gem search without anchors matches partial names - gem search rail returns rails, rails-api, railties, etc. Always use ^name$ for exact matches.

2. Bundler lockfile platform - Gemfile.lock records the platform. Moving between architectures (x86 to ARM) requires bundle lock --add-platform <platform>.

3. System Ruby vs user Ruby - On macOS, the system Ruby (/usr/bin/ruby) is managed by Apple and should not have gems installed into it. Use rbenv, rvm, or asdf to manage Ruby versions.

4. require name differs from gem name - The gem activerecord is required as active_record. The gem rspec-core is required as rspec/core. Check the gem's README for the correct require path.

5. Yanked gems - Gem authors can yank versions from RubyGems.org. Yanked versions won't appear in search results but may still be in existing Gemfile.lock files.

6. Pre-release versions - Pre-release versions (e.g. 8.0.0.rc1) are not installed by default. Use gem install rails --pre or specify the exact version.

7. Native extension build failures - Gems with C extensions (nokogiri, pg, mysql2) require system libraries. Common fixes:

   # nokogiri
   brew install libxml2 libxslt  # macOS
   
   # pg (PostgreSQL)
   brew install postgresql       # macOS
   
   # mysql2
   brew install mysql            # macOS

Rust Crates Reference

CLI Commands

cargo search (primary lookup)

# Search for a crate by name
cargo search serde --limit 1
# Output: serde = "1.0.219"    # A generic serialization/deserialization framework

# Search with more results
cargo search http --limit 10

# The output format is: name = "version"    # description
# Parse carefully - extract just the version between quotes

Gotcha: cargo search output includes a description after the version number. When extracting the version programmatically, parse only the content between the first pair of double quotes after =.

cargo add (add dependency)

# Add latest version (built-in since Rust 1.62)
cargo add serde

# Add with specific features
cargo add serde --features derive
cargo add tokio --features full

# Add specific version
cargo add serde@1.0.219

# Add as dev dependency
cargo add --dev criterion

# Add as build dependency
cargo add --build cc

# Dry run to see what would change
cargo add serde --dry-run

For Rust versions before 1.62, cargo add requires the cargo-edit crate:

cargo install cargo-edit

cargo update

# Update all dependencies to latest compatible versions
cargo update

# Update a specific crate
cargo update serde

# Update to a specific version
cargo update serde --precise 1.0.219

crates.io API

Base URL: https://crates.io/api/v1

Critical: crates.io requires a User-Agent header on all API requests. Requests without it return 403 Forbidden.

Get crate metadata

# Get crate info (requires User-Agent header)
curl -s -H "User-Agent: live-dep-resolver" \
  https://crates.io/api/v1/crates/serde | jq '.crate.max_version'

# Get specific version info
curl -s -H "User-Agent: live-dep-resolver" \
  https://crates.io/api/v1/crates/serde/1.0.219 | jq '.version.num'

# List all versions
curl -s -H "User-Agent: live-dep-resolver" \
  https://crates.io/api/v1/crates/serde/versions | jq '.versions[].num' | head -10

# Get download count
curl -s -H "User-Agent: live-dep-resolver" \
  https://crates.io/api/v1/crates/serde | jq '.crate.downloads'

# Search for crates
curl -s -H "User-Agent: live-dep-resolver" \
  'https://crates.io/api/v1/crates?q=json&per_page=5' | jq '.crates[].name'

Check crate existence

# Returns 200 if exists, 404 if not
curl -s -o /dev/null -w "%{http_code}" \
  -H "User-Agent: live-dep-resolver" \
  https://crates.io/api/v1/crates/some-crate-name

Feature Flags

Rust crates use feature flags to enable optional functionality:

# Cargo.toml - enabling features
[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
reqwest = { version = "0.12", features = ["json", "rustls-tls"] }

# Default features are enabled automatically
# To disable them:
serde_json = { version = "1.0", default-features = false }

Checking available features

# Via API
curl -s -H "User-Agent: live-dep-resolver" \
  https://crates.io/api/v1/crates/tokio/1.43.0 | jq '.version.features'

# Via docs.rs (human-readable)
# https://docs.rs/tokio/latest/tokio/#feature-flags

Common feature patterns:

• derive - Proc macro derives (serde, thiserror)
• full - All features enabled (tokio)
• json - JSON support (reqwest)
• rustls-tls / native-tls - TLS backend selection
• async - Async runtime support

Cargo.toml Version Requirements

Note: Cargo's default "1.0.219" is equivalent to npm's ^1.0.219. This is the recommended way to specify versions - it allows patch and minor updates while preventing breaking changes.

Workspace dependencies (monorepo)

# Root Cargo.toml
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

# Member Cargo.toml
[dependencies]
serde = { workspace = true }
tokio = { workspace = true }

Common Gotchas

1. crates.io API requires User-Agent - Any request without a User-Agent header returns 403. Always include one: -H "User-Agent: my-app".

2. cargo search output needs parsing - The output format is name = "version" # description. Don't include the description text when extracting the version.

3. Feature flags can change between versions - A feature available in v1.0 may be renamed or removed in v2.0. Always check features for the specific version being installed.

4. Yanked versions - Crate authors can yank versions (similar to npm deprecation). Yanked versions won't be selected by cargo but can still be used if already in Cargo.lock. The API field is version.yanked.

5. cargo add availability - Built into cargo since Rust 1.62 (June 2022). For older toolchains, install cargo-edit: cargo install cargo-edit.

6. Crate name vs module name - Crate names use hyphens (serde-json) but Rust code uses underscores (serde_json). The registry treats them as equivalent but use statements require underscores.

7. Build scripts and proc macros - Some crates require a C compiler or system libraries. openssl-sys needs OpenSSL headers; ring needs a C compiler. Check the crate's README for system dependencies.