@code-pushup/cli

@code-pushup/cli

🔎🔬 Quality metrics for your software project. 📉🔍

• ⚙️ Configure what you want to track using your favourite tools.
• 🤖 Integrate it in your CI.
• 🌈 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

• Install as a dev dependency with your package manager:

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

  yarn add --dev @code-pushup/cli
  

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

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

  export default {
    persist: {
      outputDir: '.code-pushup',
      format: ['json', 'md'],
    },
    plugins: [
      // ...
    ],
    categories: [
      // ...
    ],
  };
  

• 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';
  
  export default {
    // ...
    plugins: [
      // ...
      await eslintPlugin({ eslintrc: '.eslintrc.js', patterns: ['src/**/*.js'] }),
    ],
  };
  

• Define your custom categories.

  export default {
    // ...
    categories: [
      {
        slug: 'performance',
        title: 'Performance',
        refs: [
          {
            type: 'audit',
            plugin: 'eslint',
            slug: 'react-jsx-key',
            weight: 1,
          },
          // ...
        ],
      },
      // ...
    ],
  };
  

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

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

Portal integration

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

export default {
  // ...
  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 }}

CLI commands and options

Global Options

Option	Type	Default	Description
--progress	boolean	true	Show progress bar in stdout.
--verbose	boolean	false	When true creates more verbose output. This is helpful when debugging.
--config	string	code-pushup.config.js	Path to the config file, e.g. code-pushup.config.js

Common Command Options

Option	Type	Default	Description
--persist.outputDir	string	n/a	Directory for the produced reports.
--persist.filename	string	report	Filename for the produced reports without extension.
--persist.format	('json' | 'md')[]	json	Format(s) of the report file.
--upload.organization	string	n/a	Organization slug from portal.
--upload.project	string	n/a	Project slug from portal.
--upload.server	string	n/a	URL to your portal server.
--upload.apiKey	string	n/a	API key for the portal server.
--onlyPlugins	string[]	[]	Only run the specified plugins. Applicable to all commands except upload.

[!NOTE]
All common options, expect --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 the necessary plugins, runs them, and then collects the results. After collecting 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 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.