# Manage Your Projects

The `shishoctl project` command suite provides comprehensive project management capabilities for Shisho Cloud. This guide covers all project-related operations including project lifecycle, member management, scope configuration, and notification setup.

## Prerequisites

Before using project commands, ensure you have:

1. Installed `shishoctl` (see [Installation](/docs/c/accessing-via-shishoctl-cli/index.md#installation))
2. Authenticated with Shisho Cloud:
   ```shell
   shishoctl auth signin
   ```
3. Your organization ID (available from the Shisho Cloud dashboard URL)

## Project Lifecycle Management

### Creating a Project

Create a new project in your organization:

```shell
shishoctl project create --org <ORGANIZATION_ID> --name <PROJECT_NAME> [--description <DESCRIPTION>]
```

**Example:**

```shell
shishoctl project create --org org-a --name "Web Application Security" --description "Security analysis for our web applications"
```

For automation scripts, use `--quiet` to get only the project ID:

```shell
PROJECT_ID=$(shishoctl project create --org org-a --name "My Project" --quiet)
echo "Created project: $PROJECT_ID"
```

### Listing Projects

List all projects in your organization:

```shell
shishoctl project list --org <ORGANIZATION_ID>
```

**With pagination:**

```shell
# Show first 25 projects
shishoctl project list --org org-a --per-page 25 --page 0

# Show second page with 50 projects per page
shishoctl project list --org org-a --per-page 50 --page 1
```

**Output formats:**

```shell
# JSON output (default)
shishoctl project list --org org-a --format json

# YAML output
shishoctl project list --org org-a --format yaml
```

### Deleting a Project

Delete a project (use with caution):

```shell
shishoctl project delete --org <ORGANIZATION_ID> --project <PROJECT_ID>
# Skip confirmation prompt
shishoctl project delete --org <ORGANIZATION_ID> --project <PROJECT_ID> --force
```

**Example:**

```shell
shishoctl project delete --org org-a --project proj-123 --force
```

:::warning
Project deletion is irreversible. The `--force` flag skips the confirmation prompt.
:::

## Member Management

### Adding Members

**Add existing organization users:**

```shell
# First, get the user ID
USER_ID=$(shishoctl organization users describe --org <ORGANIZATION_ID> --email <USER_EMAIL> --id)

# Add user to project with role
shishoctl project member add --org <ORGANIZATION_ID> --project <PROJECT_ID> --user <USER_ID> --role <ROLE>
```

**Invite new users:**

```shell
shishoctl project member invite --org <ORGANIZATION_ID> --project <PROJECT_ID> --email <USER_EMAIL> --role <ROLE>
```

**Available roles:**

- `owner` - Full project access
- `triager` - Can triage findings
- `viewer` - Read-only access

**Example workflow:**

```shell
# Try to find existing user
USER_EMAIL="alice@company.com"
USER_ID=$(shishoctl organization users describe --org org-a --email $USER_EMAIL --id)

if [ -z "$USER_ID" ]; then
  echo "User not found, sending invitation"
  shishoctl project member invite --org org-a --project proj-123 --email $USER_EMAIL --role viewer
else
  echo "Adding existing user"
  shishoctl project member add --org org-a --project proj-123 --user $USER_ID --role owner
fi
```

### Listing Members

View all project members:

```shell
shishoctl project member list --org <ORGANIZATION_ID> --project <PROJECT_ID>
```

### Removing Members

Remove a user from the project:

```shell
shishoctl project member remove --org <ORGANIZATION_ID> --project <PROJECT_ID> --user <USER_ID>
```

## Scope Management

Project scopes define which cloud resources the project monitors.

### Listing Current Scope

```shell
shishoctl project scope list --org <ORGANIZATION_ID> --project <PROJECT_ID>
```

### Adding Cloud Accounts to Scope

**Method 1: Using Shisho Cloud Resource ID**

```shell
# Get the Shisho Cloud resource ID of the integrated cloud account
RESOURCE_ID=$(shishoctl cloud-account describe --org <ORGANIZATION_ID> --googlecloud-project-number <GOOGLECLOUD_PROJECT_NUMBER> --id)

# Add to project scope
shishoctl project scope add --org <ORGANIZATION_ID> --project <PROJECT_ID> --scope <RESOURCE_ID>
```

**Method 2: Direct Google Cloud Project Number**

```shell
shishoctl project scope add --org <ORGANIZATION_ID> --project <PROJECT_ID> --googlecloud-project-number <GOOGLECLOUD_PROJECT_NUMBER>
```

**Example:**

```shell
# Add Google Cloud project to scope
GOOGLECLOUD_PROJECT_NUMBER="514893259785"
shishoctl project scope add --org org-a --project proj-123 --googlecloud-project-number $GOOGLECLOUD_PROJECT_NUMBER
```

### Removing from Scope

```shell
shishoctl project scope remove --org <ORGANIZATION_ID> --project <PROJECT_ID> --scope <RESOURCE_ID>
```

## Notification Management

Configure notification channels for project alerts.

### Listing Current Notifications

```shell
shishoctl project notification list --org <ORGANIZATION_ID> --project <PROJECT_ID>
```

### Setting Up Email Notifications

```shell
# Set email notification
shishoctl project notification set --org <ORGANIZATION_ID> --project <PROJECT_ID> --email <USER_EMAIL>
```

:::note
The email address to set notification on must be in the allowlist of your organization.
:::

### Setting Up Notification Groups

```shell
# List available notification groups
shishoctl organization notification group list --org <ORGANIZATION_ID>

# Set notification group
shishoctl project notification set --org <ORGANIZATION_ID> --project <PROJECT_ID> --notification-group <GROUP_ID>
```

### Setting Up Slack Notifications

```shell
shishoctl project notification set --org <ORGANIZATION_ID> --project <PROJECT_ID> --slack-workspace-id <WORKSPACE_ID> --slack-channel-id <CHANNEL_ID>
```

:::info

The slack channel must be already integrated with your organization.
:::

### Removing Notifications

```shell
# List current notification channel IDs to remove
shishoctl project notification list --org <ORGANIZATION_ID> --project <PROJECT_ID>

# Remove notifications
shishoctl project notification delete --org <ORGANIZATION_ID> --project <PROJECT_ID> <CHANNEL_ID>
```

## Complete Project Setup Example

Here's a complete example that creates a project and sets it up with members, scope, and notifications:

```shell
#!/bin/bash

# Configuration
ORGANIZATION_ID="org-a"
PROJECT_NAME="Production Security"
USER_EMAIL="security@company.com"
GOOGLECLOUD_PROJECT_NUMBER="514893259785"

# Authenticate
shishoctl auth signin

# Create project
echo "Creating project: $PROJECT_NAME"
PROJECT_ID=$(shishoctl project create --org $ORGANIZATION_ID --name "$PROJECT_NAME" --quiet)
echo "Created project: $PROJECT_ID"

# Add user as owner
echo "Adding user as project owner"
USER_ID=$(shishoctl organization users describe --org $ORGANIZATION_ID --email $USER_EMAIL --id)
if [ -n "$USER_ID" ]; then
  shishoctl project member add --org $ORGANIZATION_ID --project $PROJECT_ID --user $USER_ID --role owner
  echo "Added user $USER_EMAIL as owner"
else
  shishoctl project member invite --org $ORGANIZATION_ID --project $PROJECT_ID --email $USER_EMAIL --role owner
  echo "Invited user $USER_EMAIL as owner"
fi

# Add Google Cloud project to scope
echo "Adding Google Cloud project to scope"
shishoctl project scope add --org $ORGANIZATION_ID --project $PROJECT_ID --googlecloud-project-number $GOOGLECLOUD_PROJECT_NUMBER

# Set up email notifications
echo "Setting up email notifications"
shishoctl project notification set --org $ORGANIZATION_ID --project $PROJECT_ID --email $USER_EMAIL

# Verify setup
echo "=== Project Setup Complete ==="
echo "Members:"
shishoctl project member list --org $ORGANIZATION_ID --project $PROJECT_ID

echo "Scope:"
shishoctl project scope list --org $ORGANIZATION_ID --project $PROJECT_ID

echo "Notifications:"
shishoctl project notification list --org $ORGANIZATION_ID --project $PROJECT_ID
```

## Common Patterns and Tips

### Pagination for Large Lists

When dealing with many projects, use pagination:

```shell
# Get all projects in batches
PAGE=0
PER_PAGE=50

while true; do
  PROJECTS=$(shishoctl project list --org $ORGANIZATION_ID --page $PAGE --per-page $PER_PAGE)
  PROJECT_COUNT=$(echo "$PROJECTS" | jq 'length')

  if [ "$PROJECT_COUNT" -eq 0 ]; then
    break
  fi

  echo "Processing page $PAGE with $PROJECT_COUNT projects"
  # Process projects...

  PAGE=$((PAGE + 1))
done
```

### Conditional Operations

Check state before making changes:

```shell
# Only add scope if not already present
CURRENT_SCOPE=$(shishoctl project scope list --org $ORGANIZATION_ID --project $PROJECT_ID)
SCOPE_COUNT=$(echo "$CURRENT_SCOPE" | jq 'length')

if [ "$SCOPE_COUNT" -eq 0 ]; then
  echo "Adding cloud account to empty scope"
  shishoctl project scope add --org $ORGANIZATION_ID --project $PROJECT_ID --googlecloud-project-number $GOOGLECLOUD_PROJECT_NUMBER
else
  echo "Project scope already configured"
fi
```

## Check Command Details

For detailed information about any command, use the `--help` flag:

```shell
shishoctl project --help
shishoctl project create --help
shishoctl project member --help
```

For organization-level operations (users, teams, notification groups), see the organization commands:

```shell
shishoctl organization --help
```