# CloudZero Operations CLI

CloudZero Operations Command Line Interface (`czops`) provides administrative functions for managing CloudZero platform systems. For authorized CloudZero employees only.

## Documentation

| Guide | Description |
|-------|-------------|
| **[Command Reference](docs/guides/commands.md)** | Complete reference for all commands and options |
| **[Installation](docs/guides/installation.md)** | Installation and upgrade instructions |
| **[Getting Started](docs/guides/getting-started.md)** | First steps, authentication, and basic usage |
| **[Troubleshooting](docs/guides/troubleshooting.md)** | Common issues and solutions |
| **[Configuration](docs/reference/configuration.md)** | Settings, environment variables, config files |
| **[Contributing](docs/development/contributing.md)** | Development workflow and contribution guide |
| **[Coding Standards](docs/development/coding-standards.md)** | Code style, linting, and quality standards |
| **[Testing](docs/development/testing.md)** | Testing guidelines and procedures |
| **[Architecture](docs/development/architecture/overview.md)** | System design and architecture |
| **[Git Workflows](docs/operations/workflows.md)** | Branching, releases, and deployment |
| **[GitHub Actions](docs/operations/github-actions.md)** | CI/CD pipeline documentation |
| **[API Overview](docs/api/README.md)** | API versions and authentication |
| **[Auto-Link API](docs/api/auto-link.md)** | Auto-link command API reference |
| **[Glossary](docs/reference/glossary.md)** | Terms and definitions |
| **[Release Notes](docs/releases/index.md)** | Version history |

## Features

- **Organization Management** -- List, search, enable/disable, refresh, tags, healthcheck
- **Connection Administration** -- List, healthcheck, reconfigure, link, enable/disable, resource collection
- **Auto-Link** -- Enable, disable, status, ignore, failure analysis, and triage for AWS account auto-discovery
- **Authentication** -- Okta OAuth 2.0 login, logout, test, refresh, user info
- **Anomaly Detection** -- Download reviewable anomalies, upload review decisions
- **Document Management** -- Upload, download, list, and delete organization documents
- **QuickSight** -- Dashboard listing, dataset creation/deletion, SPICE reporting
- **CostFormation** -- Convert CSV mapping files to CostFormation YAML
- **Shell Access** -- Assume IAM roles into connected AWS accounts
- **Utilities** -- CZRN/ARN conversion, CloudWatch metrics, web app launcher

Run `czops --help` for a complete list of available commands.

## Installation

### Production Install (uv tool)

```bash
# Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.zshrc

# Install cz-ops-cli
uv tool install cz-ops-cli --extra-index-url https://pypi.cloudzero.com

# Verify
czops --version
```

For detailed installation options (including global uv config and pipx alternative), see the **[Installation Guide](docs/guides/installation.md)**.

### Upgrade

```bash
uv tool upgrade cz-ops-cli --extra-index-url https://pypi.cloudzero.com
```

### Development Setup

```bash
git clone https://github.com/Cloudzero/cz-ops-cli.git
cd cz-ops-cli
uv sync
source .venv/bin/activate
```

## Development Commands

| Command | Description |
|---------|-------------|
| `./scripts/test.sh` | Run the test suite |
| `./scripts/lint.sh` | Run the linter (ruff) |
| `./scripts/build.sh` | Build the project (runs lint and test first) |
| `./scripts/clean.sh` | Clean temporary files and build artifacts |
| `./scripts/help.sh` | View available commands |

## Development Workflow

This project uses **trunk-based development** with linear history.

```
feature/fix-branch --> main (PR + review + auto-deploy)
```

1. Create a feature branch from `main`
2. Develop and test (`./scripts/test.sh && ./scripts/lint.sh`)
3. Create PR to `main`
4. On merge, GitHub Actions deploys to PyPI and creates a Git tag

For full workflow details, see **[Git Workflows](docs/operations/workflows.md)**.

## Quick System Tests

```bash
czops --version
czops auth test
czops org list cloudzero --debug
czops connection list 02fa7d30-c3de-4e0a-8f1e-2de120e7fd23
```

## Project Structure

```
src/
+-- api/        # API client interfaces to CloudZero backend services
+-- features/   # CLI command implementations organized by feature
+-- utils/      # Shared utility functions and helpers
+-- lib/        # CloudZero-specific utilities and integrations
+-- schemas/    # Pydantic models and schema definitions
```

## Requirements

- Python 3.10+
- Okta authentication (via `czops auth login`)
- AWS credentials (for shell and CWM commands)

## License

Proprietary -- All Rights Reserved, CloudZero.

## Support

For issues, contact the CloudZero tools team at `#cz-tools` on internal Slack.
