api
Call an API endpoint the CLI has no command for.
A direct call to the Out Plane API, for the endpoints this CLI has no command for yet. It handles the credential, the team header and the response envelope, so what is left is the method and the path.
It is an escape hatch and reads like one. It cannot tell what a call will change, so
anything other than a read needs --yes, and under an agent harness a write is
refused whatever flags it is given. Where a named command exists, use that instead:
it validates, it explains its errors, and it knows what it changed.
Usage
outplane api <METHOD> <PATH> [flags]Arguments
| Argument | Type | Description |
|---|---|---|
METHOD | string | GET, POST, PUT, PATCH or DELETE. Required. |
PATH | string | The part after /api, such as /App/GetAppsByTeamId. Required. |
Flags
| Flag | Type | Description |
|---|---|---|
-d, --data | string | JSON body. @file.json reads a file, @- reads standard input. |
--query | strings | Key=value, repeatable. Safer than putting & in a shell argument. Repeatable. |
--raw | bool | Print the whole response envelope instead of its data. |
-y, --yes | bool | Acknowledge a call that is not a read. Refused under an agent harness whatever it says. |
The global flags apply as well.
Examples
Read an endpoint the CLI has no command for
outplane api GET /App/GetAppsByTeamIdPass query parameters without fighting the shell
outplane api GET /AppDeployment/GetAppDeployments --query appId=<APP_ID> --query page=1See the whole envelope rather than its data
outplane api GET /App/GetAppsByTeamId --raw{
"data": [],
"isSuccessful": true,
"statusCode": 200
}Check what a write would send, without sending it
outplane api POST /AppSetting/AddEnvironmentVariables/<APP_ID> --data '{"environmentVariables":{"A":"1"}}' --dry-runSend a body too large for a command line
cat body.json | outplane api POST /Some/Endpoint --data @- --yesWhat to Know
- This command has no output fields, because the shape of the answer belongs to the endpoint. --fields is refused with usage.no_fields. The output is one JSON document: the envelope's data, or the whole envelope with --raw.
- An endpoint that returns nothing prints null, so the output is always one JSON document and never an empty stream.
- A write is refused under an agent harness with exit 4 and confirmation.required, whatever flags are given. The commands that name what they change are the way to make a change from an agent, and they exist for everything the CLI covers;
outplane schemalists them. - Outside a harness, anything other than GET needs --yes. There is no --confirm-name here, because this command cannot tell which resource is being changed or what it is called.
- The path is joined to the configured API address and cannot be a full URL, so this command cannot be pointed at another host.
- Failures map to the same exit codes as every other command: 3 for a rejected credential, 5 for not found, 7 for a plan limit, 8 for a server failure. The response body of a failure travels in the error's details.
- A body must be JSON. It is checked before the request is sent, so a typo fails with api.body_invalid rather than as a server-side 400.
Errors
Beyond 0 for success, this command exits with:
| Exit | Kind | Meaning |
|---|---|---|
1 | internal | An unexpected failure in the CLI itself. |
2 | usage | Invalid arguments, unknown flag, or client-side validation failure. |
3 | auth | Not authenticated, token revoked or expired, or forbidden for this team. |
4 | confirmation_required | A destructive operation stopped. Replay the command in confirm_command. |
5 | not_found | The named resource does not exist, or is not visible to this credential. |
6 | conflict | The resource already exists, or a concurrent change won. |
7 | quota | Plan limit reached or payment required. Not a rate limit; retrying will not help. |
8 | upstream | The Out Plane API returned a server error. |
The code on the error object is one of api.method_invalid, api.path_required, api.path_invalid, api.query_invalid, api.body_invalid, api.body_not_allowed, api.body_unreadable, confirmation.required, usage.missing_argument. Branch on that, or on the exit status. The message is prose and changes.