alpacon api

Send one request to the Alpacon API of the current workspace, using the identity you signed in with.

Usage#

alpacon api ENDPOINT [flags]

Key facts#

• ENDPOINT is a path on the current workspace, such as /api/iam/users/. An absolute URL or another host is refused.
• With no -X, the method is GET, or POST once you pass a field or --input.
• Fields go to the query string for GET and HEAD, and to a JSON body for other methods. With --input, they always go to the query string.
• The response body goes to stdout even for an error; an error also prints HTTP <code> to stderr and exits with code 1.
• When an action needs a fresh MFA check, the CLI shows the MFA link and sends the request again once you finish.

Flags#

Examples#

Show your own user record

alpacon api /api/iam/users/-/

Search users, with the status line and response headers

alpacon api -X GET -i -f search=admin /api/iam/users/

Create a resource from typed fields (sent as POST)

alpacon api -F name=my-server /api/servers/servers/

Update a resource from a JSON file

alpacon api -X PATCH --input update.json /api/servers/servers/123/

Request fields#

-f key=value always sends a string. -F key=value reads the value first:

Bracket keys build nested values. -f 'tags[]=one' -f 'tags[]=two' sends an array, and -f 'filter[name]=demo' sends an object. In a query string the brackets stay in the parameter name.

With --input, the file (or standard input for --input -) is the request body, and any -f/-F fields go to the query string. POST, PUT, and PATCH requests are sent as Content-Type: application/json; pass -H 'Content-Type: ...' for another body type. Only one field or --input can read standard input.

Response output#

The response body is written to stdout. In a terminal, control characters are removed from the body and a JSON body is indented; piped or redirected output is left exactly as the server sent it, so jq and other tools read the original body.

-i adds the status line and response headers before the body, and --verbose prints the request and response headers to stderr. Both show Authorization, Proxy-Authorization, Cookie, and Set-Cookie as [REDACTED]. --silent drops the body; the exit code still reports the result.

A redirect within the workspace is followed. A redirect to another host is not: the CLI prints HTTP <code> and redirect to <location> not followed to stderr and exits with code 1.

Permissions and MFA#

A request runs with the permissions of the identity you signed in with through alpacon login. The server refuses what that identity cannot do, and the refusal body is printed like any other response. See the API reference for endpoints and error codes.

Some actions, such as granting a role, need a fresh MFA check. When the server asks for one, the CLI prints the workspace MFA link, opens it in your browser when one is available, and waits for about three minutes while you finish MFA. It then sends the request again and prints only the final response. If the wait runs out, the server’s response is printed, stderr shows its HTTP <code> and MFA authentication timed out, and the command exits with code 1.

When you pass your own -H 'Authorization: ...' header, the CLI sends it unchanged and does not open an MFA prompt. A token cannot complete MFA, so sign in as yourself for actions that need a fresh check.

Exit codes#

• 0: the server answered with a 2xx status.
• 1: the server answered with another status, the request could not be sent, or an unknown flag was passed.
• 2: the endpoint, method, a field, a header, or the input file was invalid. Nothing was sent.

Related#

• API reference
• API tokens
• alpacon login
• alpacon whoami