# Operating with the shishoctl CLI

The `shishoctl` CLI is a tool for operating Shisho Cloud. With this tool, you can deploy and manage policies on Shisho Cloud, providing an experience similar to using the `docker` or `kubectl` commands.

## Installation

The following commands install `shishoctl` for each supported environment:

<Tabs>
<TabItem value="linux-amd64" label="Linux (amd64)" default>

You can install `shishoctl` to `/usr/local/bin` with the following command:

```sh
SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-x86_64-unknown-linux-gnu"
sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
sudo chmod +x /usr/local/bin/shishoctl
```

</TabItem>

<TabItem value="linux-arm64" label="Linux (arm64)">

You can install `shishoctl` to `/usr/local/bin` with the following command:

```sh
SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-aarch64-unknown-linux-gnu"
sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
sudo chmod +x /usr/local/bin/shishoctl
```

</TabItem>

<TabItem value="apple-amd64" label="macOS (Intel CPU)">

You can install `shishoctl` to `/usr/local/bin` with the following command:

```sh
SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-x86_64-apple-darwin"
sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
sudo chmod +x /usr/local/bin/shishoctl
```

</TabItem>

<TabItem value="apple-arm64" label="macOS (Apple Silicon)">

You can install `shishoctl` to `/usr/local/bin` with the following command:

```sh
SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-aarch64-apple-darwin"
sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
sudo chmod +x /usr/local/bin/shishoctl
```

</TabItem>

<TabItem value="windows-amd64" label="Windows (amd64)">

Either use the Linux binary with an environment like WSL, or download from [https://shisho.dev/releases/shishoctl-0.15.0-x86_64-pc-windows-gnu.exe](https://shisho.dev/releases/shishoctl-0.15.0-x86_64-pc-windows-gnu.exe) and use it as `shishoctl.exe`.

</TabItem>

</Tabs>

## Sign in

By running the following command in an environment where the `shishoctl` command can be executed, you can sign in to Shisho Cloud from `shishoctl`:

```shell
shishoctl auth signin
```

:::note
The authentication information obtained from Shisho Cloud by the `shishoctl auth signin` command expires after a certain period. If you encounter an authentication error, please run the `shishoctl auth signin` command again.
:::

### Sign in as a Bot

When accessing Shisho Cloud in environments where a browser is not available, such as CI/CD or server environments, you can sign in using a bot account. There are two methods for signing in as a bot.

#### Sign in with Trust Conditions (for use with GitHub Actions / GitLab CI)

For OIDC-compliant environments like GitHub Actions and GitLab CI, we recommend using authentication based on trust conditions. This method is more secure because it eliminates the need to manage API keys.

For more details, please refer to the following documentation:

- [Managing Rules with SCM - GitHub](/docs/g/getting-started/deploy-policies-with-git-repositories/github.md)
- [Managing Rules with SCM - GitLab](/docs/g/getting-started/deploy-policies-with-git-repositories/gitlab.md)

#### Sign in with an API Key

For bot authentication in environments that are not OIDC-compliant, you can use an API key to access Shisho Cloud from `shishoctl`.

API keys are associated with bots. Therefore, if you have not yet created a bot, you should create one first. Follow these steps:

1. Access the [bots list](https://cloud.shisho.dev/*/settings/bots) page
2. Click the "Add Bot" button to create a new bot

Once created, you can issue an API key by following these steps:

1. Access the [bots list](https://cloud.shisho.dev/*/settings/bots) page.
2. Click on the name of the bot you created to open its detail page.
3. In the API Key tab, click "Create API Key" to create a new API key for the bot.

:::warning Important
API keys are only displayed once at creation time. You cannot retrieve them later, so make sure to save them in a secure location when they are created.
:::

To sign in using an API key, run the following command:

```shell
shishoctl auth signin:bot \
  --bot <Bot ID> \
  --api-key-json "$(cat api-key.json)"
```

The `api-key.json` file must be in the following JSON format:

```json
{
  "api_key": "shisho_apikey_..."
}
```

Alternatively, you can specify the API key directly:

```shell
shishoctl auth signin:bot \
  --bot <Bot ID> \
  --api-key-json '{"api_key":"shisho_apikey_..."}'
```

:::info
The Bot ID is an ID starting with `BT`. After creating a bot on the [bot creation page](https://cloud.shisho.dev/*/settings/bots), you can find it in the URL of the bot's details page.

https://cloud.shisho.dev/{ORGANIZATION_ID}/settings/bots/{BOT_ID}
:::

:::warning Security Best Practices

Like API keys for general SaaS products, if a bot's API key is leaked, data on Shisho Cloud may be compromised. To handle them securely, please keep the following in mind:

- Do not publicly expose API keys. In particular, do not commit them to public repositories such as GitHub.
- When storing API keys in private locations, use the most secure location possible. For example, use GitHub Actions' secret management feature rather than including them directly in a GitHub repository.
- Delete API keys promptly when they are no longer needed.
  :::

#### Choosing an Authentication Method

The following table shows the recommended authentication methods for different environments. Please select the method that best suits your environment.

| Environment              | Recommended Authentication Method |
| ------------------------ | --------------------------------- |
| GitHub Actions           | Trust Conditions (OIDC)           |
| GitLab CI                | Trust Conditions (OIDC)           |
| Other CI/CD Environments | API Key                           |

## Example: Get a list of workflows

Once successfully signed in via the `shishoctl` CLI, you can perform a range of operations on Shisho Cloud using `shishoctl`. For example, the following command retrieves a list of workflows registered to the organization ID `org-a`:

```shell
shishoctl workflow list -o org-a
```

:::info
The organization ID refers to the ID registered when [creating an organization](/docs/g/getting-started/create-an-organization.md). If the organization ID is unclear, please follow the steps below to check it:

1. Open the Shisho Cloud dashboard in a web browser.
2. Check the organization ID (the `[oid]` part) in the URL displayed in your web browser, as shown below:

```
https://cloud.shisho.dev/[oid]/dashboard
```

:::

## Example: Chaining Multiple Commands

The `shishoctl` CLI outputs data in JSON or YAML format. This allows you to process the output of one command and use it as input for another, enabling complex chained operations.

For example, the following is a Python script that retrieves a list of findings in an organization, then gets the information of the resources targeted by each finding, and displays them together. Before running, please set the environment variables `SHISHOCTL_ORG_ID` (Organization ID) and `SHISHOCTL_PROJECT_ID` (Project ID).

```python
import subprocess
import yaml
import os

org_id = os.getenv("SHISHOCTL_ORG_ID")
project_id = os.getenv("SHISHOCTL_PROJECT_ID")

result = subprocess.run(
  ["shishoctl", "project", "finding", "list", "--org", org_id, "--project", project_id, "--format", "yaml"],
  capture_output=True,
  text=True,
)
parsed = yaml.safe_load(result.stdout)

summary = {"entries": []}
for i, finding in enumerate(parsed["entries"]):
  api_version = finding["id"]["apiVersion"]
  kind = finding["id"]["kind"]

  result = subprocess.run(
    ["shishoctl", "finding", "describe", "--org", org_id, api_version, kind],
    capture_output=True,
    text=True,
  )
  parsed = yaml.safe_load(result.stdout)

  summary["entries"].append({
    "id": {
      "apiVersion": api_version,
      "kind": kind,
    },
    "subjects": [],
  })

  for entry in parsed["decisions"]["entries"]:
    summary["entries"][i]["subjects"].append(entry['header']['subject'])

print(yaml.dump(summary))
```

## Checking How to Use Other Commands

For more information on how to use the `shishoctl` command, please see other pages on this website or run the following command:

```shell
shishoctl --help
```