> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidocsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Install and log in
> Install the Vidoc CLI, create an API key, and connect the CLI to your Vidoc API.
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](/integrations/github), [GitLab](/integrations/gitlab), or [Bitbucket](/integrations/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 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](/web-app/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
```bash theme={null}
npm install -g @vidocsecurity/cli
```
Make sure that the installation is correct:
```bash theme={null}
vidoc version
```
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](https://app.vidoc.dev) or your custom deployment URL, then select **Project switcher > API keys**. For details, refer to [Settings](/web-app/settings#api-keys).
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](/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](/cli/configuration#configuration-file). Replace the example keys and API addresses below with your own.
```bash theme={null}
vidoc login "your-api-key"
```
The CLI uses the cloud API `https://api.vidoc.dev` by default. You do not need `--url`.
```bash theme={null}
vidoc login "your-api-key" --url https://api.example.com
```
Give `--url` each time that you log in. If you run `vidoc login` without `--url`, the CLI sets the API address of the profile back to the cloud API `https://api.vidoc.dev`.
If you do not give the key, the CLI asks for it and hides what you type:
```bash theme={null}
vidoc login
```
`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
| Option | Default | Effect |
| - | - | - |
| `[token]` | none | The API key. If you do not give it, the CLI asks for it. |
| `--url ` | `https://api.vidoc.dev` | The API address. The CLI keeps only the protocol, the host, and the port. If you do not give a protocol, the CLI uses `https://`. |
| `--profile ` | `default` | The profile to create or replace. |
| `--debug` | off | Show debug output. |
### Use more than one profile
Use profiles when you work with more than one project or more than one Vidoc installation:
```bash theme={null}
vidoc login "your-project-a-api-key" --profile project-a
vidoc login "your-project-b-api-key" --profile project-b --url https://api.example.com
```
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](/cli/configuration#profiles).
`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](/cli/configuration#keep-the-key-in-an-environment-variable).
## Update the CLI
```bash theme={null}
npm install -g @vidocsecurity/cli
```
When a newer version is available, the CLI shows a message with this command.
## Uninstall the CLI
```bash theme={null}
npm uninstall -g @vidocsecurity/cli
```
The uninstall does not remove the configuration file. To remove your saved keys, delete the file. For its location, refer to [Configuration](/cli/configuration#configuration-file).
## 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
Run your first scan.
Scan the changes of a branch in CI.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.