Skip to main content
Use the vidoc command-line interface (CLI) to scan a local copy of a repository, or to scan the changes of a branch in a CI pipeline. The CLI uploads the files to Vidoc, starts a scan, and shows the validated issues in the terminal.
Pull request reviews through the GitHub, GitLab, or Bitbucket integration do not need the CLI. Use the CLI when you want to scan code on your computer or in your own pipeline.

​
Requirements

  • Node.js 20 or later (recommended) and npm.
  • Git. The CLI uses Git to find the repository, the branch, and the changed files.
  • Network access to the Vidoc API:
    • Vidoc Cloud: https://api.vidoc.dev
    • Self-hosted: https://api.<your-domain>. Your admin gives you the address.
  • A Vidoc account with the Developer, Security Engineer, or Admin role. The Read Only role cannot create API keys. For roles, refer to Navigation and roles.
When you run vidoc scan, vidoc ci, or vidoc export, the CLI also connects to registry.npmjs.org to look for a newer version. If the registry is not available, the command continues.

​
Install the CLI

Make sure that the installation is correct:
The command shows the installed version, for example Vidoc CLI version: 0.1.21.

​
Create an API key

The CLI and the REST API use the same API keys.
  1. Open app.vidoc.dev or your custom deployment URL, then select Project switcher > API keys. For details, refer to Settings.
  2. Click Create new key.
  3. Type a name, for example Laptop or CI pipeline.
  4. Select the expiry: 1 day, 1 week, 1 month (default), 6 months, or 1 year.
  5. Click Create, then copy the key.
A key gives access to one project only. It has the permissions of the user who created it. For more information, refer to API authentication.
Keep the key secret. Do not commit it to a repository. In a CI system, keep it in the secret store.

​
Log in

vidoc login saves the API key and the API address in a profile in the configuration file. Replace the example keys and API addresses below with your own.
The CLI uses the cloud API https://api.vidoc.dev by default. You do not need --url.
If you do not give the key, the CLI asks for it and hides what you type:
vidoc login does not send a request to Vidoc. The CLI uses the key for the first time when you run a scan. If the key is not correct, the scan stops with an authentication error.

​
Login options

​
Use more than one profile

Use profiles when you work with more than one project or more than one Vidoc installation:
When you log in to a profile that is not default, the CLI makes it the current profile. To change the current profile, and for all profile commands, refer to Configuration.
vidoc login stores the key as plain text in the configuration file. On a shared computer, use an environment variable for the key. Refer to Keep the key in an environment variable.

​
Update the CLI

When a newer version is available, the CLI shows a message with this command.

​
Uninstall the CLI

The uninstall does not remove the configuration file. To remove your saved keys, delete the file. For its location, refer to Configuration.

​
Troubleshooting

The global npm folder is not in your PATH. Find the folder with npm config get prefix, then add its bin folder to PATH in your shell profile.
The key is missing, not valid, expired, or it belongs to a different Vidoc installation.
  1. Run vidoc config show. Make sure that the current profile has the correct API address.
  2. Create a new key and run vidoc login again. On a self-hosted installation, give --url.
  3. If you use VIDOC_TOKEN or VIDOC_API_URL, make sure that they have the correct values. Environment variables override the profile.
The key is valid, but the role of the user who created the key does not permit the action. Or that user no longer has access to the project. Ask an admin to check your role and your project access.
On Vidoc Cloud, the organization has no active subscription. Scans do not start without a subscription. An admin can set up the plan in the web app.
Make sure that your computer can connect to the API address. Check your VPN and proxy settings. Run the command again with --debug to see the full error.

​
Next steps

Scan code

Run your first scan.

CI/CD pipelines

Scan the changes of a branch in CI.