> 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.p0.dev/getting-started/getting-started-with-the-p0-cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.