# Shares CLI Commands

> The soat CLI commands for the Shares module, with usage and every option, generated from the OpenAPI spec.

# Shares Commands

See [Shares module docs](../../modules/shares) for permissions and data model.

### `soat create-share`

Create a share

- Method: `POST`
- Path: `/api/v1/shares`

#### Usage

```bash
soat create-share --resource <string> --actions <array<string>> --grantee <string>
```

#### Options

##### `--project-id`

The publishing project (required if not using project key auth)

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--resource`

The SRN of one resource in the publishing project, `srn:<project_id>:<type>:<id>`. No wildcard.

- Source: `body`
- Required: yes
- Type: `string`
- Example: `srn:proj_V1StGXR8Z5jdHi6B:tool:tool_V1StGXR8Z5jdHi6B`

##### `--actions`

The actions granted: `tools:CallTool` for a `tool`, `agents:CreateAgentGeneration` for an `agent`. Any other action is `400 VALIDATION_FAILED`.

- Source: `body`
- Required: yes
- Type: `array<string>`
- Example: `["tools:CallTool"]`

##### `--grantee`

The project the share is offered to, or `*` for every project. Never the publishing project itself.

- Source: `body`
- Required: yes
- Type: `string`
- Example: `proj_Q1StGXR8Z5jdHi6B`

##### `--cap`

The calls each accepting project may make through the share per fixed window; a call past it is `429 SHARE_CAP_EXCEEDED`. Omit or `null` for no cap.

- Source: `body`
- Required: no
- Type: `object`

### `soat list-shares`

List shares

- Method: `GET`
- Path: `/api/v1/shares`

#### Usage

```bash
soat list-shares
```

#### Options

##### `--project-id`

Project ID (required if not using project key auth, and always for `role=grantee`)

- Source: `query`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--role`

Which side of the shares to list

- Source: `query`
- Required: no
- Type: `enum("publisher", "grantee")`
- Default: `publisher`

##### `--resource`

Only shares of this resource SRN (`role=publisher` only)

- Source: `query`
- Required: no
- Type: `string`
- Example: `srn:proj_V1StGXR8Z5jdHi6B:tool:tool_V1StGXR8Z5jdHi6B`

### `soat get-share`

Get a share

- Method: `GET`
- Path: `/api/v1/shares/{share_id}`

#### Usage

```bash
soat get-share
```

#### Options

##### `--project-id`

The project the caller reads as. Omit, or name the publisher, for the publisher's view; name a grantee project for its view.

- Source: `query`
- Required: no
- Type: `string`
- Example: `proj_Q1StGXR8Z5jdHi6B`

### `soat update-share`

Update a share

- Method: `PATCH`
- Path: `/api/v1/shares/{share_id}`

#### Usage

```bash
soat update-share
```

#### Options

##### `--cap`

The calls each accepting project may make through the share per fixed window; a call past it is `429 SHARE_CAP_EXCEEDED`. `null` removes the cap.

- Source: `body`
- Required: no
- Type: `object`

### `soat delete-share`

Delete a share

- Method: `DELETE`
- Path: `/api/v1/shares/{share_id}`

#### Usage

```bash
soat delete-share
```

#### Options

This command has no options.

### `soat accept-share`

Accept a share

- Method: `POST`
- Path: `/api/v1/shares/{share_id}/accept`

#### Usage

```bash
soat accept-share
```

#### Options

##### `--project-id`

The accepting project (required if not using project key auth)

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_Q1StGXR8Z5jdHi6B`

### `soat suspend-share`

Suspend a share

- Method: `POST`
- Path: `/api/v1/shares/{share_id}/suspend`

#### Usage

```bash
soat suspend-share
```

#### Options

This command has no options.

### `soat resume-share`

Resume a share

- Method: `POST`
- Path: `/api/v1/shares/{share_id}/resume`

#### Usage

```bash
soat resume-share
```

#### Options

This command has no options.

### `soat revoke-share`

Revoke a share

- Method: `POST`
- Path: `/api/v1/shares/{share_id}/revoke`

#### Usage

```bash
soat revoke-share
```

#### Options

##### `--force`

As a grantee, revoke even while the project's resources name the shared resource; they degrade as for a revoked share.

- Source: `query`
- Required: no
- Type: `boolean`
- Default: `false`

##### `--project-id`

The project the caller revokes for. Omit, or name the publisher, to revoke the share; name a grantee project to revoke its acceptance.

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_Q1StGXR8Z5jdHi6B`

### `soat list-share-references`

List a grantee's references to a shared resource

- Method: `GET`
- Path: `/api/v1/shares/{share_id}/references`

#### Usage

```bash
soat list-share-references
```

#### Options

##### `--project-id`

The grantee project whose references to list.

- Source: `query`
- Required: no
- Type: `string`
- Example: `proj_Q1StGXR8Z5jdHi6B`

### `soat list-share-acceptances`

List a share's acceptances

- Method: `GET`
- Path: `/api/v1/shares/{share_id}/acceptances`

#### Usage

```bash
soat list-share-acceptances
```

#### Options

##### `--status`

Only acceptances in these statuses. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.

- Source: `query`
- Required: no
- Type: `array<enum("active", "revoked")>`

### `soat revoke-share-acceptance`

Revoke an acceptance

- Method: `POST`
- Path: `/api/v1/shares/{share_id}/acceptances/{acceptance_id}/revoke`

#### Usage

```bash
soat revoke-share-acceptance
```

#### Options

This command has no options.

### `soat delete-share-acceptance`

Delete an acceptance

- Method: `DELETE`
- Path: `/api/v1/shares/{share_id}/acceptances/{acceptance_id}`

#### Usage

```bash
soat delete-share-acceptance
```

#### Options

This command has no options.