> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/getting-started/getting-started-with-the-p0-cli.md).

# Getting Started with the P0 CLI

This tutorial walks you through the P0 command-line interface (CLI) from installation to your first permission request and SSH session. By the end, you have installed the CLI, authenticated with your organization, sent a Google Cloud role request, and connected to a machine over SSH with just-in-time access.

## Steps to get started

1. [Install the P0 CLI](#install-the-p0-cli)
2. [Authenticate with your organization](#authenticate-with-your-organization)
3. [Send your first permission request](#send-your-first-permission-request)
4. [Discover SSH targets](#discover-ssh-targets)
5. [Open your first SSH session](#open-your-first-ssh-session)
6. [Copy files with SCP](#copy-files-with-scp)

{% hint style="info" %}
This process takes about 10 minutes, assuming your organization has already configured an SSH integration.
{% endhint %}

## Prerequisites

Before you begin, confirm the following:

* **P0 account** — You have an account at [p0.app](https://p0.app) and belong to an organization.
* **SSH integration** — Your administrator has installed the SSH access control integration for at least one cloud provider (AWS, Google Cloud, or Azure). See the [SSH integration guide](/integrations/resource-integrations/ssh.md) for setup instructions.
* **Node.js v22+** — Required for npm installation. Check with `node --version`.

{% hint style="info" %}
If you prefer a standalone binary that bundles Node.js, see the platform-specific installation guides for [macOS](/p0-cli/installing-p0-cli/macos.md) and [Windows](/p0-cli/installing-p0-cli/windows.md).
{% endhint %}

**Provider-specific prerequisites:**

| Provider     | Required tools                                                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AWS          | [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + [Session Manager plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) |
| Google Cloud | [gcloud CLI](https://cloud.google.com/sdk/docs/install) (the CLI runs `gcloud auth login` automatically when needed)                                                                                                                  |
| Azure        | [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) (authenticated with `az login`)                                                                                                                            |

## Install the P0 CLI

Install the CLI globally with npm:

```bash
npm install -g @p0security/cli
```

Verify the installation:

```bash
p0 --version
```

You should see the installed version number. Run `p0 help` to view all available commands.

{% hint style="info" %}
For alternative installation methods, including standalone macOS and Windows binaries, see [Installing p0 CLI](/p0-cli/installing-p0-cli.md).
{% endhint %}

## Authenticate with your organization

Log in to your P0 organization. Replace `<your-org>` with your organization ID (visible in your P0 URL at `p0.app/o/<your-org>`):

```bash
p0 login <your-org>
```

Your browser opens to your organization's SSO provider (Google, Okta, Microsoft, or another configured provider). After you authenticate, the CLI confirms:

```
You are now logged in to the <your-org> organization, and can use the p0 CLI.
```

{% hint style="info" %}
The CLI stores your session in `~/.p0/identity.json`. If your session expires, the CLI automatically re-launches the browser login flow the next time you run a command.
{% endhint %}

## Send your first permission request

The P0 CLI can request any permission that your organization supports — cloud IAM roles, resources, SSH access, and more. This section walks through requesting a Google Cloud IAM role as an example.

### Find available roles

List Google Cloud roles that contain "storage" in the name:

```bash
p0 ls gcloud role storage
```

The output displays matching roles available to you, such as `storage.objectViewer`, `storage.admin`, and others.

{% hint style="info" %}
Use the `--like` flag for multi-term searches. For example, `--like storage,admin` returns roles matching both "storage" and "admin".
{% endhint %}

### Request the role

Request the `storage.objectViewer` role on a Google Cloud project. Replace `<your-project>` with your Google Cloud project ID:

```bash
p0 request gcloud role storage.objectViewer \
  --project <your-project> \
  --reason "Review storage bucket contents" \
  --wait
```

The `--wait` flag blocks until the request is approved and access is provisioned. You see output similar to:

```
Will wait up to 5 minutes for this request to complete...
Your request was approved
Waiting for access to be provisioned
Access to role storage.objectViewer has been provisioned
```

Once provisioned, you can use `gcloud` commands under the granted role immediately.

{% hint style="info" %}
Without `--wait`, the CLI submits the request and returns immediately. You receive a notification (through Slack or your configured channel) when access is approved and provisioned.
{% endhint %}

{% hint style="warning" %}
Google Cloud IAM changes have a propagation delay of 30 seconds to one minute. If a `gcloud` command fails immediately after provisioning, wait briefly and retry.
{% endhint %}

### Other request types

The `p0 request` command supports providers beyond Google Cloud. Run `p0 request --help` to see all options:

| Provider     | Example                                                            |
| ------------ | ------------------------------------------------------------------ |
| AWS          | `p0 request aws role MyReadOnlyRole --account 123456789012`        |
| Google Cloud | `p0 request gcloud role storage.objectViewer --project my-project` |
| Okta         | `p0 request okta group engineering-team`                           |

For the full command reference, see [`p0 request`](/p0-cli/p0-commands-and-usage/p0-request.md).

## Discover SSH targets

Before connecting, list the SSH destinations available to you:

```bash
p0 ls ssh session destination
```

This displays instances your organization has registered with P0. To filter by cloud provider, add the `--provider` flag:

{% tabs %}
{% tab title="AWS" %}

```bash
p0 ls ssh session destination --provider aws
```

{% endtab %}

{% tab title="Google Cloud" %}

```bash
p0 ls ssh session destination --provider gcloud
```

{% endtab %}

{% tab title="Azure" %}

```bash
p0 ls ssh session destination --provider azure
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Items marked with `*` indicate instances you already have active access to. Listing a destination does not grant access — you still need approval.
{% endhint %}

To see more results, use the `--size` flag:

```bash
p0 ls ssh session destination --size 50
```

## Open your first SSH session

Connect to an instance by name. Replace `<instance-name>` with a destination from the previous step:

{% tabs %}
{% tab title="AWS" %}

```bash
p0 ssh <instance-name> \
  --provider aws \
  --reason "Testing P0 CLI access"
```

{% endtab %}

{% tab title="Google Cloud" %}

```bash
p0 ssh <instance-name> \
  --provider gcloud \
  --reason "Testing P0 CLI access"
```

{% endtab %}

{% tab title="Azure" %}

```bash
p0 ssh <instance-name> \
  --provider azure \
  --reason "Testing P0 CLI access"
```

{% endtab %}
{% endtabs %}

The CLI performs these steps automatically:

1. Generates a temporary SSH key pair.
2. Submits a just-in-time access request to P0 (including your `--reason`).
3. Waits for approval (up to 5 minutes).
4. Provisions access on the cloud provider.
5. Establishes the SSH connection.

You see output similar to:

```
Will wait up to 5 minutes for this request to complete...
Your request was approved
Waiting for access to be provisioned
```

Once provisioning completes, you are connected to the instance.

{% hint style="warning" %}
Most cloud providers have a propagation delay of 10 to 30 seconds after access is approved before the connection succeeds. The CLI retries automatically during this window.
{% endhint %}

{% hint style="info" %}
Use the `--sudo` flag to request sudo access on the remote machine:

```bash
p0 ssh <instance-name> --provider aws --sudo --reason "Install security patch"
```

{% endhint %}

### Run a one-off command

To execute a single command without an interactive session, append it after the destination:

```bash
p0 ssh <instance-name> --provider gcloud -- "df -h /var"
```

### Forward a local port

Use SSH port forwarding to securely access remote services:

```bash
p0 ssh <instance-name> --provider aws -- -L 5432:localhost:5432
```

This forwards local port 5432 to the remote instance's port 5432, useful for connecting to databases.

## Copy files with SCP

The `p0 scp` command works like standard `scp` but includes automatic access requests. Prefix the remote path with the instance name and a colon:

**Download a file from the remote instance:**

```bash
p0 scp <instance-name>:/var/log/app.log ./app.log \
  --provider aws \
  --reason "Collect logs for debugging"
```

**Upload a file to the remote instance:**

```bash
p0 scp ./config.yaml <instance-name>:/tmp/config.yaml \
  --provider gcloud \
  --reason "Deploy updated configuration"
```

## Verify it worked

Confirm your request history by checking the **Access Management > History** page at `https://p0.app/o/<your-org>/access-management/history`. You should see your completed permission request and SSH access request with the reasons you provided.

## Troubleshooting

| Symptom                                                 | Cause                         | Fix                                                                                                                             |
| ------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `The organization ID is required`                       | Missing org argument          | Run `p0 login <your-org>` with your org ID                                                                                      |
| `This organization is not configured for SSH access`    | No SSH integration installed  | Ask your admin to install the [SSH integration](/integrations/resource-integrations/ssh.md)                                     |
| `Could not find any instances matching...`              | Incorrect destination name    | Run `p0 ls ssh session destination` to list valid names                                                                         |
| `Your request was denied`                               | Approver denied the request   | Check your policies or contact your approver                                                                                    |
| Request times out after 5 minutes                       | No approver responded         | Verify your organization's [request routing policies](/access-management/just-in-time-access/request-routing.md) are configured |
| `Access did not propagate through <provider> in time`   | Cloud provider delay exceeded | Retry the command — transient delays resolve on retry                                                                           |
| `Hint: The instance name appears to include a username` | Used `user@host` format       | Use the instance name only, without a username prefix                                                                           |

For detailed troubleshooting, see [p0 ssh troubleshooting](/p0-cli/troubleshooting/p0-ssh.md).

## What's next

Now that you can request permissions and SSH into machines from the command line, explore these capabilities:

* [Request access to AWS, Azure, Okta, and more](/p0-cli/p0-commands-and-usage/p0-request.md) with `p0 request`
* [Integrate P0 SSH with your native SSH config](/integrations/resource-integrations/ssh.md) to use `ssh <instance-name>` directly
* [Request access for a colleague](/access-management/just-in-time-access/requesting-access/for-another-party.md) with `p0 grant`
* [Create pre-approvals](/access-management/just-in-time-access/approving-access/pre-approving-access.md) for frequently accessed instances with `p0 allow`
* [Configure routing rules](/access-management/just-in-time-access/request-routing.md) to auto-approve access for on-call engineers
* Explore all [CLI commands and usage](/p0-cli/p0-commands-and-usage.md)