cli

Subscribe to all “cli” posts via RSS or follow GitHub Changelog on Twitter to stay updated on everything we ship.

→ ~ cd github-changelog
→ ~/github-changelog|main git log main
showing all changes successfully

npm v9.0.0 released

The npm CLI team has been working hard over the past few months and are happy to announce the release of the next major version – v9.0.0

Installation

You can start using npm v9.0.0 today by running:

$ npm i -g npm@9

About this release

Our goal with this major release was to standardize appropriate defaults and clean up legacy configurations where possible. We believe the changes made lay the ground-work for future improvements to the default npm experience long-term. Notably, Docker users should find this release to to be beneficial as we simplifie file permissions (ref. #5703 & #5704).

Timeline to GA

Although we have published v9.0.0, we are not immediately setting this release to latest in the npm registry or considering this “Generally Available.” Our team has been coordinating with the Node.js Release WG on a phased approach to making v9 the next major version of the CLI available to the widest audience; this means ensuring v9 can be safely backported to as many Node.js LTS versions as possible. With that in mind, we’ve put together a phased roll-out plan outlined below:

  • Wednesday Oct. 19th
    • npm@9.0.0 was released & set to the next-9 dist-tag (previously used for pre-releases)
    • The CLI team will continue to cut minor & patch versions of v9.x, addressing any feedback or unexpected issues arising from the breaking changes (outlined below)
  • Wednesday Nov. 9th (General Availability)
    • To ensure npm@9.x is considered "non-breaking" for Node.js LTS we will codify a set of exit criteria in collaboration with the Release WG
    • npm@9.x will be set to the latest dist-tag (becoming the latest, maintained version of npm)
    • A PR will be opened to land npm@9.x in nodejs/node's main branch (exposing experimental/nightly users to this latest version)
  • Wednesday Dec. 7th (~4 weeks after GA)
    • A PR will be opened to backport npm@9.x in node@19
  • Wednesday Jan. 18th (~6 weeks after node@19 backport)
    • A PR will be opened to backport npm@9.x in node@18

⚠️ Notable Breaking Changes

  • the compatible semver ranges of node have been updated to: ^14.17.0 || ^16.13.0 || >=18.0.0
  • npm will no longer attempt to modify ownership of files it creates
  • the presence of auth related settings that are not scoped to a specific registry found in a config file is no longer supported and will throw errors
  • login, adduser, and auth-type changes
    • legacy auth types sso, saml & legacy have been consolidated into "legacy"
    • auth-type defaults to "web"
    • login and adduser are now separate commands that send different data to
      the registry.
  • npm pack now follows a strict order of operations when applying ignore rules. If a files array is present in the package.json, then rules in .gitignore and .npmignore files from the root will be ignored.
  • links generated from git urls will now use HEAD instead of master as the default ref
  • timing and loglevel changes
    • timing has been removed as a value for --loglevel
    • --timing will show timing information regardless of
      --loglevel, except when --silent
  • --timing file changes:
    • When run with the --timing flag, npm now writes timing data to a
      file alongside the debug log data, respecting the logs-dir option and
      falling back to <CACHE>/_logs/ dir, instead of directly inside the
      cache directory.
    • The timing file data is no longer newline delimited JSON, and instead
      each run will create a uniquely named <ID>-timing.json file, with the
      <ID> portion being the same as the debug log.
    • Finally, the data inside the file now has three top level keys,
      metadata, timers, and unfinishedTimers instead of everything being
      a top level key.
  • npm now outputs some json errors on stdout. Previously npm would output all json formatted errors on stderr, making it difficult to parse as the stderr stream usually has logs already written to it.
  • deprecated boolean install flags in favor of --install-strategy
    • deprecated --global-style, --global now sets --install-strategy=shallow
    • deprecated --legacy-bundling, now sets --install-strategy=nested
  • npm config set will no longer accept deprecated or invalid config options
  • install-links config defaults to "true"
  • node-version config has been removed
  • npm-version config has been removed
  • npm access subcommands have been renamed
  • npm birthday has been removed
  • npm set-script has been removed
  • npm bin has been removed (use npx or npm exec to execute binaries)

Notable Features

  • a09e19d #5696 new npm config fix command (@nlf)
  • 3445da0 npm timings are now written alongside debug log files (@lukekarrys)
  • 6ee5b32 query: now displays queryContext in results (@nlf)
  • 314311c #5550 separated login/adduser (@wraithgar)
  • de2d33f add --install-strategy=hoisted|nested|shallow (#5709) (@fritzy)

For more information about this release, check out the GitHub release notes.

See more

Introducing the new npm Dependency Selector Syntax

npm query is a new top-level command as of npm v8.16.0 which accepts a Dependency Selector (as defined in the Dependency Selector Syntax Specification) & returns a filtered JSON Array/NodeList of dependencies from your project. We believe this capability has been a missing piece of the package management ecosystem; With its introduction we hope to unlock the potential for developers to self-serve in asking new, complex questions about their dependencies, their relationships & associative metadata.

For many JavaScript developers, the Dependency Selector Syntax will look very familiar as it is actually an adapted form of CSS. We leveraged this existing, known language & its operators to make disparate package information broadly accessible.

Example Uses:

If I wanted to list all of my dependencies (similar to npm list --all) I can run:

npm query "*"

If I wanted to find every version of react & lodash in my project I can run:

npm query "#react, #lodash"

If I wanted to find all react versions not-defined as a peer dependency I can run:

npm query "#react:not(.peer)"

If I wanted to find all the dependencies in my project that used an MIT license I'd change that query to be:

npm query "[license=MIT]"

If I wanted to find all the git dependencies in my project I can run:

npm query ":type(git)"

If I wanted to find out which of my transitive dependencies used a postinstall script I could run:

npm query ":attr(scripts, [postinstall]):not(:root > *)"

Programmatic Usage

We know many developers in the ecosystem will also want to leverage this new syntax themselves, so we've built it right into the programmatic brain of the CLI. Under the hood, we’ve added a new .querySelectorAll() method to the existing Node Class we use in the @npmcli/arborist library. Tooling authors can now load up & query their dependencies just like we do.

// index.js
const Arborist = require('@npmcli/arborist')
const arb = new Arborist({})

arb.loadActual((tree) => {
  // query all workspaces
  const results = await tree.querySelectorAll('.workspace')
  console.log(results)
})

You can learn more about the syntax & usage in our documentation here: https://docs.npmjs.org/cli/v8/using-npm/dependency-selectors

What's next?

Looking ahead we’ve got work planned to add new pseudo states & selectors based on registry metadata that should unlock another host of capabilities aimed at auditing (examples include: :outdated :deprecated :vulnerable :cve() & :cwe()). As documented in the original RFC proposal we will also consider supporting a query flag or reading from stdin to existing commands.

See more

GitHub CLI extension to manage Actions cache

You can now manage Actions cache from your terminal by installing the new GitHub CLI extension for Actions cache:

    gh extension install actions/gh-actions-cache

This extension is built on top of GitHub APIs for cache management and enables you to get:

  • More transparency by listing all the active caches in a repository and sorting by metadata like cache size, creation time or last accessed time.
  • Better control over cache usage by deleting a corrupt or a stale cache entry

Learn more about dependency caching to speed up your Actions workflows.

See more

Codespaces now have a configurable idle timeout

By default Codespaces time out after 30 minutes of inactivity. We’ve heard from many users that they have a desire to extend this up to an entire workday. You can now set a default idle timeout for your codespaces from five minutes to four hours, as well as override the idle timeout for an individual codespace using the gh CLI.

For more information, see “Setting your timeout period for Codespaces”.

See more

New Codespaces features launching at Universe 2021

GitHub Codespaces allows teams and organizations to spin-up developer environments directly from a browser or through Visual Studio Code, without the hassle of setting up a brand new environment tailored to a specific repository.

We've been hard at work since our general availability announcement in August making Codespaces the best way for you to develop software, which is why we're so happy to announce several new features at GitHub Universe 2021.

We know that many developers use the gh CLI to speed up or fully automate daily tasks, and we've received dozens of requests to add Codespaces support to the CLI. As of today, the gh codespace (or gh cs for those saving keystrokes) command now allows developers to manage their codespaces from the GitHub CLI. In addition to codespace creation, listing, and starting/stopping, users can forward ports, set port visibility, SSH into their codespaces, and copy files to/from their codespaces.

# Create a new codespace via the CLI
gh codespace create --repo monalisa/octocat --branch main

We're especially excited about ssh access, as it allows developers who prefer to use editors like vim and emacs to more easily develop in Codespaces. Just gh cs ssh into your codespace and launch your editor of choice; we'll set up the environment and grab all your dotfiles so you're ready to develop in seconds.

# SSH into the codespace created above
gh codespace ssh -c monalisa-monalisa-octocat-1337h4x0r

Complimenting the CLI, we are also launching an API in beta. The API provides control plane operations around a user's codespaces including creating, starting/stopping, listing available machine types, and setting user secrets. These APIs will allow developers to build Codespaces integrations into their favorite editors and tools, as well as allow for additional automation around Codespaces.

# Stop a running codespace via the API
curl https://api.github.com/user/codespaces/monalisa-monalisa-octocat-1337h4x0r/stop \
  -H "Authorization: token <Personal Access Token>" \
  -X POST

We also know that security and privacy are critical, and we've gotten a lot of feedback on providing additional visibility options for forwarded ports beyond public and private. Today we're launching a third option: org visible ports, which are accessible to any user in the organization the codespace has been created in. This is great for securely collaborating with your teammates on new and exciting features in your codespaces.

# Make port 80 visible to all users in an org
gh codespace ports visibility 80:org -c monalisa-monalisa-octocat-1337h4x0r

Continuing with security improvements, we have also heard from developers having difficulty launching codespaces from devcontainers stored in private container registries. To make this easier, we are offering streamlined access to containers stored in the GitHub Container Registry; you no longer have to provide a Personal Access Token (PAT).

Speaking of devcontainers, we know that there's a wide gap between using a predefined devcontainer and building a custom devcontainer. To help make that transition a little easier, we're launching the ability to extend devcontainers with features, which include shells, package managers, programming languages, and other common tools. For example, adding Terraform to a supported base image is as easy as adding the following to your devcontainer.json.

"features": {
  "terraform": "latest"
}

If you have any feedback about these features, or Codespaces in general, we'd love to hear from you!

Learn more about all our newly released features:

See more

GitHub CLI 1.9 enables you to work with GitHub Actions from your terminal

GitHub CLI 1.9 allows you to work with GitHub Actions in your terminal:

  • List and view workflows and runs with gh workflow list, gh workflow view, gh run list, and gh run view
  • View the logs for a particular run with gh run view --log
  • View the logs for runs with jobs that failed with gh run view --log-failed
  • Download run artifacts with gh run download
  • Re-run runs with failed jobs using gh run rerun
  • Watch runs in progress using gh run watch
  • Trigger workflows with the workflow_dispatch event using gh workflow run
  • Enable and disable workflows with gh workflow enable and gh workflow disable

Learn more about GitHub CLI and check out the blog post to learn more about this release.

See more