# Command reference

This reference uses the same v1 command grammar as the SSH service.

Every command accepts `--json`. Mutation commands accept `--request-id ID`.
Creation, start, stop and deletion also accept `--timeout SECONDS` (1–3600,
default 120) and `--no-wait`. Memory is in MiB and disk size is in GiB.
Image identifiers are immutable `sha256:` digests returned by `images`.
Use `--after UUID` with the returned cursor to fetch another list page.

## exit

`exit`

Close this interactive channel.

Options: `--json`.

## help

`help [COMMAND]`

Show command help.

Options: `--json`.

## images

`images`

List available images.

Options: `--json`.

## ls

`ls [--after CURSOR]`

List machines you can access.

Options: `--json`, `--after`.

## new

`new [--name NAME] [--image DIGEST] [--profile PROFILE] [--cpu N] [--memory MIB] [--disk GIB]`

Create a machine.

Options: `--json`, `--name`, `--image`, `--profile`, `--cpu`, `--memory`, `--disk`, `--request-id`, `--timeout`, `--no-wait`.

## request show

`request show REQUEST_ID`

Inspect a previously accepted request.

Options: `--json`.

## rm

`rm MACHINE`

Delete a machine and its disk.

Options: `--json`, `--request-id`, `--timeout`, `--no-wait`.

## share add

`share add MACHINE EMAIL ROLE`

Grant viewer, operator or manager access.

Options: `--json`, `--request-id`.

## share remove

`share remove MACHINE EMAIL`

Revoke an account's shared access.

Options: `--json`, `--request-id`.

## share show

`share show MACHINE [--after CURSOR]`

List access grants.

Options: `--json`, `--after`.

## show

`show MACHINE`

Inspect a machine by name or UUID.

Options: `--json`.

## ssh-key list

`ssh-key list`

List your SSH keys.

Options: `--json`.

## ssh-key remove

`ssh-key remove UUID`

Revoke one of your SSH keys.

Options: `--json`, `--request-id`.

## start

`start MACHINE`

Start a machine.

Options: `--json`, `--request-id`, `--timeout`, `--no-wait`.

## stop

`stop MACHINE`

Stop a machine, retaining its disk.

Options: `--json`, `--request-id`, `--timeout`, `--no-wait`.

## whoami

`whoami`

Show the authenticated account.

Options: `--json`.

Permissions are checked at execution time. Access shown in a previous list is
not a guarantee that a later operation is allowed. Sharing roles are `viewer`,
`operator` and `manager`; ownership and current permissions determine which
operations you may perform. SSH key commands affect only your own keys.

```porsche
help share add
ls --json
share add example-machine colleague@example.invalid viewer
share show example-machine
share remove example-machine colleague@example.invalid
ssh-key list
```