> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pensar.dev/apex/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pensar.dev/apex/_mcp/server.

# pensar apps

> Manage the workspace attack surface — apps and endpoints — via the Pensar Console API

## Overview

The `pensar apps` command lets you manage your **attack surface** — the applications and endpoints Pensar knows about — through the Pensar Console API. You can list, view, create, update, and delete apps, and do the same for the endpoints that belong to them. It also exposes the workspace's domains, so you can resolve the domain an app links to without leaving the terminal.

All commands operate on the **selected workspace**, which is chosen when you connect with [`pensar login`](/apex/cli-commands/pensar-login). Apps and endpoints are scoped to that workspace — there is no project argument.

## Usage

```bash
pensar apps                                   # List apps in the workspace (alias: pensar apps list)
pensar apps get <appId>                        # Show app details
pensar apps create [options]                   # Create an app
pensar apps update <appId> [options]           # Update an app
pensar apps delete <appId>                     # Delete an app
pensar apps domains                            # List workspace domains
pensar apps domain-create <domain>             # Create/resolve a domain
pensar apps endpoints <appId> [filters]        # List an app's endpoints
pensar apps endpoint <endpointId>              # Show endpoint details
pensar apps endpoint-create <appId> [options]  # Create an endpoint
pensar apps endpoint-update <endpointId> [options]  # Update an endpoint
pensar apps endpoint-delete <endpointId>       # Delete an endpoint
pensar apps search <query> [options]           # Substring-search apps
pensar apps search-endpoints <query> [options] # Substring-search endpoints
```

## Prerequisites

You must be connected to Pensar Console via [`pensar login`](/apex/cli-commands/pensar-login) before using this command. Every subcommand acts on the workspace you are logged into.

## App Subcommands

### List Apps

```bash
pensar apps
```

Lists apps in the selected workspace. Responses are paginated and returned as JSON of the form `{ apps, hasMore, limit, offset }`.

| Flag           | Description                      |
| -------------- | -------------------------------- |
| `--limit <n>`  | Page size (default 100, max 200) |
| `--offset <n>` | Page offset (default 0)          |

To page through all apps, increment `--offset` by `--limit` until `hasMore` is `false`.

### Get App Details

```bash
pensar apps get <appId>
```

Returns detailed information about a single app, including its description and disallowed-actions notes.

### Create an App

```bash
pensar apps create --name <name> --description <description> [options]
```

Creates a new app in the workspace. `--name` and `--description` are required.

| Flag                          | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `--name <text>`               | Application name (**required**)                                    |
| `--description <text>`        | Application description (**required**)                             |
| `--type <type>`               | Application type (see [App types](#app-types))                     |
| `--framework <text>`          | Framework / runtime hint                                           |
| `--domain <id>`               | Linked domain UUID (see [Domain Subcommands](#domain-subcommands)) |
| `--disallowed-actions <text>` | Free-form disallowed-actions notes                                 |

### Update an App

```bash
pensar apps update <appId> [options]
```

Updates one or more fields on an existing app. Only the flags you pass are changed; the same field flags as `create` are accepted (all optional here).

| Flag                          | Description                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| `--name <text>`               | New application name                                                   |
| `--description <text>`        | New description                                                        |
| `--type <type>`               | New application type                                                   |
| `--framework <text>`          | New framework / runtime hint                                           |
| `--domain <id>`               | New linked domain UUID (see [Domain Subcommands](#domain-subcommands)) |
| `--disallowed-actions <text>` | New disallowed-actions notes                                           |

### Delete an App

```bash
pensar apps delete <appId>
```

Deletes an app from the workspace. Returns `{ success, appId }`.

## Domain Subcommands

Apps link to a domain by UUID via `--domain`. These two subcommands are how you find or mint that UUID.

### List Domains

```bash
pensar apps domains
```

Lists the domains in the selected workspace as `{ domains }`, where each entry is `{ id, url, verified }`. Use the `id` as the `--domain` value on `apps create` or `apps update`.

### Create a Domain

```bash
pensar apps domain-create <domain>
```

Creates a domain in the workspace and returns `{ id, url, verified }`.

> **Note**
>
> Domains created through the API are canonicalized and created idempotently — passing a domain that already exists returns the existing record rather than failing. They stay **unverified** and do not start reconnaissance. Verification happens in Console.

## Endpoint Subcommands

### List Endpoints

```bash
pensar apps endpoints <appId> [filters]
```

Lists the endpoints belonging to an app. Responses are paginated and returned as JSON of the form `{ endpoints, hasMore, limit, offset }`. List responses use a lean endpoint shape — fetch a single endpoint with `endpoint <endpointId>` for the full detail (objectives, business logic, threat model, etc.).

| Flag                 | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| `--type <type>`      | Filter by endpoint type (see [Endpoint types](#endpoint-types)) |
| `--min-risk <score>` | Minimum risk score (0–10)                                       |
| `--limit <n>`        | Page size (default 100, max 200)                                |
| `--offset <n>`       | Page offset (default 0)                                         |

### Get Endpoint Details

```bash
pensar apps endpoint <endpointId>
```

Returns full detail for a single endpoint, including its objectives, authentication requirements, risk-score breakdown, business-logic notes, and threat model.

### Create an Endpoint

```bash
pensar apps endpoint-create <appId> --endpoint <path> --description <description> [options]
```

Creates an endpoint under the given app. `--endpoint` and `--description` are required.

| Flag                      | Description                                                                          |
| ------------------------- | ------------------------------------------------------------------------------------ |
| `--endpoint <text>`       | Endpoint path / URL / route (**required**)                                           |
| `--description <text>`    | Endpoint description (**required**)                                                  |
| `--type <type>`           | Endpoint type (see [Endpoint types](#endpoint-types))                                |
| `--transport <transport>` | Wire transport (see [Endpoint transports](#endpoint-transports)); defaults to `http` |
| `--location <text>`       | Source file (whitebox)                                                               |
| `--start-line <n>`        | Start line number                                                                    |
| `--end-line <n>`          | End line number                                                                      |
| `--objective <text>`      | Testing objective for the endpoint (repeatable)                                      |
| `--auth-required`         | Mark the endpoint as authentication-required                                         |
| `--no-auth-required`      | Mark the endpoint as not requiring auth                                              |
| `--auth-details <text>`   | Free-form authentication details                                                     |
| `--business-logic <text>` | Business-logic notes                                                                 |
| `--threat-model <text>`   | Per-endpoint threat-model notes                                                      |

Pass `--objective` more than once to attach multiple objectives. `--auth-required` and `--no-auth-required` are mutually exclusive.

### Update an Endpoint

```bash
pensar apps endpoint-update <endpointId> [options]
```

Updates one or more fields on an existing endpoint. Only the flags you pass are changed; every field flag from `endpoint-create` is accepted here (all optional), plus one that is update-only:

| Flag         | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| `--app <id>` | **Update only.** Move the endpoint to a different app in the workspace |

`--app` is not a valid flag on `endpoint-create` — the parent app is the positional `<appId>` argument there.

### Delete an Endpoint

```bash
pensar apps endpoint-delete <endpointId>
```

Deletes an endpoint. Returns `{ success, endpointId }`.

## Search Subcommands

Both search commands run a substring match across the selected workspace and return paginated JSON (`{ ..., hasMore, limit, offset, query }`). Search pages default to 50 (max 200).

### Search Apps

```bash
pensar apps search <query> [options]
```

| Flag            | Description                     |
| --------------- | ------------------------------- |
| `--type <type>` | Filter by application type      |
| `--limit <n>`   | Page size (default 50, max 200) |
| `--offset <n>`  | Page offset                     |

### Search Endpoints

```bash
pensar apps search-endpoints <query> [options]
```

| Flag                 | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `--app <id>`         | Scope the search to a single app (default: workspace-wide) |
| `--type <type>`      | Filter by endpoint type                                    |
| `--min-risk <score>` | Minimum risk score                                         |
| `--auth-required`    | Only auth-required endpoints                               |
| `--no-auth-required` | Only public endpoints                                      |
| `--limit <n>`        | Page size (default 50, max 200)                            |
| `--offset <n>`       | Page offset                                                |

## App types

`--type` on an app accepts one of: `ui`, `api-service`, `web-application`, `full-stack`, `domain`, `subdomain`, `database`, `cloud-resource`, `storage`.

## Endpoint types

`--type` on an endpoint accepts one of: `api-endpoint`, `web-endpoint`, `auth-endpoint`, `database`, `file-storage`, `asset`.

## Endpoint transports

`--transport` on an endpoint accepts one of: `http`, `grpc`, `grpc_web`, `connect`. Endpoints created without it default to `http`.

## Examples

```bash
# List the first page of apps in the workspace
pensar apps

# Page through apps 200 at a time
pensar apps --limit 200 --offset 200

# Create an app
pensar apps create --name "Billing API" --description "Customer billing service" --type api-service --framework "Express"

# Update an app's description
pensar apps update app_abc123 --description "Internal billing service"

# List an app's high-risk endpoints
pensar apps endpoints app_abc123 --min-risk 7

# Create an endpoint with two objectives
pensar apps endpoint-create app_abc123 \
  --endpoint "/api/invoices/:id" \
  --description "Fetch an invoice" \
  --type api-endpoint \
  --auth-required \
  --objective "Test for IDOR on invoice id" \
  --objective "Check auth bypass"

# Create a gRPC endpoint
pensar apps endpoint-create app_abc123 \
  --endpoint "orders.v1.OrderService/GetOrder" \
  --description "Fetch an order over gRPC" \
  --type api-endpoint \
  --transport grpc

# Correct an endpoint's transport after the fact
pensar apps endpoint-update endpoint_xyz789 --transport grpc_web

# Move an endpoint to a different app
pensar apps endpoint-update endpoint_xyz789 --app app_def456

# Resolve a domain, then link a new app to it
pensar apps domains
pensar apps domain-create billing.example.com
pensar apps create --name "Billing API" --description "Customer billing service" --domain <domainId>

# Search endpoints across the workspace for "login"
pensar apps search-endpoints login --auth-required

# Delete an endpoint
pensar apps endpoint-delete endpoint_xyz789
```

## Related Commands

#### [pensar pentests](/apex/cli-commands/pensar-pentests)

Dispatch and view pentests against your workspace

#### [pensar issues](/apex/cli-commands/pensar-issues)

View security issues found by pentests