@code-pushup/cli

🔎🔬 Quality metrics for your software project. 📉🔍

1. ⚙️ Configure what you want to track using your favourite tools.
2. 🤖 Integrate it in your CI.
3. 🌈 Visualize reports in a beautiful dashboard.

The Code PushUp CLI serves to collect audit results, and optionally upload the report to the Code PushUp portal.

It can be used locally in your repository, or integrated in your CI environment.

If you're looking for programmatic usage, then refer to the underlying @code-pushup/core package instead.

Getting started

1. Install as a dev dependency with your package manager:

   Installation command for npm, yarn and pnpm

   npm install --save-dev @code-pushup/cli

   yarn add --dev @code-pushup/cli

   pnpm add --save-dev @code-pushup/cli

2. Create a code-pushup.config.ts configuration file (.js or .mjs extensions are also supported).

   import type { CoreConfig } from '@code-pushup/models';
   
   const config: CoreConfig = {
     plugins: [
       // ...
     ],
   };
   
   export default config;

3. Add plugins as per your project needs (e.g. @code-pushup/eslint-plugin).

   npm install --save-dev @code-pushup/eslint-plugin

   import eslintPlugin from '@code-pushup/eslint-plugin';
   import type { CoreConfig } from '@code-pushup/models';
   
   const config: CoreConfig = {
     // ...
     plugins: [
       // ...
       await eslintPlugin({ eslintrc: '.eslintrc.js', patterns: ['src/**/*.js'] }),
     ],
   };
   
   export default config;

4. Run the CLI with npx code-pushup (see --help for list of commands and arguments).

5. View report file(s) in output directory (specified by persist.outputDir configuration).

Set up categories (optional)

1. Define your custom categories.

   const config: CoreConfig = {
     // ...
     categories: [
       {
         slug: 'performance',
         title: 'Performance',
         refs: [
           // reference to an existing audit or group from plugins
           {
             type: 'audit',
             plugin: 'eslint',
             slug: 'react-jsx-key',
             weight: 1,
           },
           // ...
         ],
       },
       // ...
     ],
   };

2. Run the CLI with npx code-pushup.

3. View report file(s) including category section in output directory.

Portal integration

If you have access to the Code PushUp portal, provide credentials in order to upload reports.

const config: CoreConfig = {
  // ...
  upload: {
    server: 'https://ip-or-domain/path/to/portal/api/graphql',
    apiKey: process.env.PORTAL_API_KEY,
    organization: 'my-org',
    project: 'my-project',
  },
};

🛠 CI automation

Example for GitHub Actions:

name: Code PushUp

on: push

jobs:
  collect-and-upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npx code-pushup autorun --upload.apiKey=${{ secrets.PORTAL_API_KEY }}

Custom Plugins

We provide comprehensive documentation on how to create a custom plugin.

The repository also maintains a set of plugin examples showcasing different scenarios.
Each example is fully tested to demonstrate best practices for plugin testing as well.

Example for custom plugins:

• 📏 File Size
• 📦 Package Json

CLI commands and options

Global Options

[!NOTE]
By default, the CLI loads code-pushup.config.(ts|mjs|js) if no config path is provided with --config.

Common Command Options

[!NOTE]
All common options, except --onlyPlugins, can be specified in the configuration file as well. CLI arguments take precedence over configuration file options.

[!NOTE]
The --upload.* group of options is applicable to all commands except collect.

Commands

collect command

Usage: code-pushup collect [options]

Description: The command initializes and executes the necessary plugins and collects the results. Based on the results it generates a comprehensive report.

Refer to the Common Command Options for the list of available options.

upload command

Usage: code-pushup upload [options]

Description: Upload reports to the Code PushUp portal.

Refer to the Common Command Options for the list of available options.

autorun command

Usage: code-pushup autorun [options]

Description: Run plugins, collect results and upload the report to the Code PushUp portal.

Refer to the Common Command Options for the list of available options.

print-config command

Usage: code-pushup print-config [options]

Description: Print the resolved configuration.

Refer to the Common Command Options for the list of available options.