> ## Documentation Index
> Fetch the complete documentation index at: https://orbit.nckrtl.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# profile

> Profile one HTTP request from the operator machine and show its timings.

`profile` sends one GET from this machine and reports its timings. Name an absolute HTTP or HTTPS URL, or pass `--instance` to profile an Instance at the URL that the Gateway records for it. [Gateway profiles](/docs/cli/gateway) are a separate local configuration.

The request always leaves this machine. The command never opens an SSH session and never asks the Gateway to send the request. With `--instance`, it asks the Gateway only for the URL.

## Commands

| Command | Result |
| - | - |
| [`profile`](#orbit-profile) | Profile one HTTP request from this machine. |

The command accepts `--json`.

## orbit profile

Profile one GET to an absolute HTTP or HTTPS URL.

```bash theme={"dark"}
orbit profile [url] [--instance=ID] [--path=PATH] [--as-first-user] [--user=ID] [--json]
```

| Argument | Required | Meaning |
| - | - | - |
| `url` | no | Absolute `http` or `https` URL to profile. Without it, the command uses `--instance` or the nearest `APP_URL`. |

| Option | Default | Meaning |
| - | - | - |
| `--instance=ID` | none | Profile the Instance with this numeric ID at its recorded URL. It cannot be combined with `url`. |
| `--path=PATH` | `/` | Path to profile on the `--instance` URL. |
| `--as-first-user` | guest | Authenticate the profiled request as the first user. |
| `--user=ID` | guest | Authenticate the profiled request as the user with this primary key. |

```bash theme={"dark"}
orbit profile https://docs.test/admin
orbit profile --instance=42 --path=/login
orbit profile https://docs.test --user=42 --json
```

Without `url` and `--instance`, the command reads `APP_URL` from the nearest `.env` in the working directory or a parent. It starts at `ORBIT_HOST_CWD` when that variable is set. An interactive terminal asks for a URL when no valid `APP_URL` exists. `--json` and `--no-interaction` fail instead.

The command sends one GET and does not follow redirects. It sends `X-REQUEST-ID` and `X-TOOLBAR-AUTH` (`guest`, `first-user`, or `user`), and `X-TOOLBAR-USER` with `--user`. TLS uses the system trust store. With `--instance`, TLS uses the active profile's pinned Orbit root certificate instead, because an Instance domain presents an Orbit CA certificate. An `--instance` request also carries `X-Orbit-Probe: 1`. A development Instance's site answers it without waking hibernated Processes and does not count it as activity.

A completed response is a success, whatever its HTTP status. When the response has a readable `X-Toolbar-Summary` header, the result has `source` `baseline+toolbar`, `instrumented` true, and the decoded summary. Otherwise `source` is `baseline` and `instrumented` is false.

Human output is one request line and a timing list. JSON returns the request, timings, response headers, auth mode, request ID, `origin` `caller`, source, and instrumented flag.

| Error code | Meaning |
| - | - |
| `profile.validation_failed` | The URL is missing or not an absolute HTTP or HTTPS URL, or `--as-first-user` and `--user` were combined. |
| `profile.request_failed` | The GET did not complete. JSON includes `origin`, `url`, and the error message. |
| `input.invalid` | `url` and `--instance` were combined. |
| `instance.id_invalid` | `--instance` is not a positive integer. |
| `instance.url_missing` | The Instance has no URL. |

## Related

* [`gateway`](/docs/cli/gateway) manages Gateway connection profiles. Those profiles are unrelated to this command.
* [`doctor`](/docs/cli/doctor) compares the Gateway's records with Node state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.