--- sidebar_label: CLI doc_id: d223a520-47d2-44c4-bcf7-d77ef5068aa3 description: >- Command-line tool for managing nullplatform resources, API interactions, and CI/CD automation. keywords: - CLI - nullplatform - API - authentication - command-line --- # CLI The nullplatform CLI allows you to: - Manage your nullplatform resources directly from the command line. - Interact with the nullplatform API. - Work with your CI/CD pipelines and automate workflows. ## Installation ### Linux and macOS - To install or update the **latest version** of the nullplatform CLI: ```bash curl https://cli.nullplatform.com/install.sh | sh ``` > 💡 Run `np --version` to check which version you have installed. - *(Not recommended)* To install a **previous version**, run: ```bash curl https://cli.nullplatform.com/install.sh | VERSION= sh ``` Replace `` with the desired version number, for example `1.2.3`. ### Windows Use one of the following options to install the CLI on Windows. #### Option 1: PowerShell (recommended) - To install the nullplatform CLI: ```powershell Invoke-WebRequest -Uri https://cli.nullplatform.com/install.ps1 -OutFile install.ps1; .\install.ps1 ``` - Install a specific version: ```powershell Invoke-WebRequest -Uri https://cli.nullplatform.com/install.ps1 -OutFile install.ps1; .\install.ps1 -Version "n.n.n" ``` #### Option 2: Batch script (Command Prompt) 1. Download the installer: ```cmd curl -o install.bat https://cli.nullplatform.com/install.bat ``` 2. Run the installer: ```cmd install.bat ``` - Install a specific version: ```cmd install.bat --version beta ``` After installation, restart your terminal so the PATH changes take effect. ### Upgrading the CLI Once the CLI is installed, you can update it in place without re-running the install script: ```bash np upgrade ``` The command checks whether a newer version is available and installs it for you. ## Authentication Before using the CLI, you need to authenticate. You can log in interactively with `np login`, or use an API key or an access token. ### Log in from the terminal If your organization uses SSO, log in with your browser straight from the terminal: ```bash np login --np-url https://.app.nullplatform.io ``` The command opens your browser to authenticate against your organization's SSO and stores the session locally, so subsequent commands authenticate automatically. You can also provide the URL through the `NP_LOGIN_URL` environment variable instead of the flag. For organizations without SSO, log in with your username and password: ```bash np login --username --password --organization-id ``` :::note `np login` is available from CLI version `2.8.0`. Run `np upgrade` if you don't have it yet. ::: ### API keys You can generate a personal or machine API key to use with the CLI. This is a persistent authentication method that can be used to generate access tokens. - Use an API key as a flag: ```bash np [command] --api-key your_api_key ``` - Or export it as an environment variable: ```bash export NULLPLATFORM_API_KEY=your_api_key_here ``` For more info on API keys, see [Manage API keys](/docs/authorization/api-keys.md). ### Access token You can also authenticate using a personal access token. - As with API keys, you can use an access token as a flag: ```bash np [command] --access-token your_access_token ``` - Or export it as an environment variable: ```bash export NP_TOKEN=your_access_token ``` #### How do I get an access token? To retrieve your personal access token: 1. Log in to nullplatform. 2. Click your **user menu** (the circle with your initials/user avatar) in the top-right corner. 3. From the dropdown menu, select **Copy personal access token**. :::warning Deprecation notice The legacy [Chrome extension](https://github.com/nullplatform/chrome-extension) used to retrieve the token is deprecated and no longer maintained or supported. ::: ### Profiles If you work with more than one nullplatform organization, or you keep separate sessions for different environments, use profiles. Each profile stores its own session, so you can switch between them without logging in again. Every command accepts `--profile`. Log in once per profile: ```bash np login --np-url https://.app.nullplatform.io --profile staging ``` Then pass the same flag to the commands you run: ```bash np application list --profile staging ``` You can also select the profile with the `NP_PROFILE` environment variable. This is useful in scripts, and for tools that inherit your shell environment, like the [MCP server](/docs/cli/mcp): ```bash export NP_PROFILE=staging np application list ``` When you don't specify a profile, the CLI uses the one named `default`. There's no registration step: logging in with a name you haven't used before creates the profile. Sessions are stored in your OS keychain when one is available, and in `~/.np/config..yml` otherwise. To log out of a profile, clear its session: ```bash np login --clear --profile staging ``` ## How to use the CLI Check out our [API reference](/docs/api-getting-started), where you'll find CLI examples for every supported endpoint. Simply search for the endpoint you need to see an example for. :::tip Use `np --help` to get information on all available commands. ::: Below is a full example for reference: ```bash title="Create an account in your organization" # Using environment variable authentication export NULLPLATFORM_API_KEY=your_api_key_here np account create --body '{ "name": "mocked-name-1", "slug": "mocked-slug-1", "organization_id": 123, "status": "active" }' # Or using command-line flag np account create --body '{ "name": "mocked-name-1", "slug": "mocked-slug-1", "organization_id": 123, "status": "active" }' --format json --access-token your_access_token # Example response: { "id": 515151, "name": "mocked-name-1", "nrn": "organization=123", "organization_id": 123, "slug": "mocked-slug-1", "status": "active" } ``` ## Browsing your organization Use `np browse` to explore your organization from the terminal without jumping to the dashboard: ```bash np browse ``` It opens an interactive tree of your hierarchy: expand accounts, namespaces, applications, and scopes, and the panel on the right shows the selected entity's details, like its id, slug, status, NRN, and, for scopes, the domain it serves. A few keys cover most of what you'll need: | Key | Action | | --- | --- | | `↑` `↓` | Move through the tree | | `Enter` / `→` | Expand an entity | | `Backspace` / `←` | Go back | | `/` | Filter the tree | | `o` | Open the selected entity in your browser | | `c` | Copy the selected entity's data | | `i` | Show or hide inactive entities | | `q` | Quit | It's the fastest way to find an application or scope, grab its id or NRN for another command, or jump straight to it in the dashboard.