projects

snyk-api

Production-Ready: Comprehensive Snyk API management tool with CLI interface.

A comprehensive Go library and CLI tool for managing Snyk APIs. Built on go-application-framework with type-safe clients generated from OpenAPI specifications.

Note: Currently developed at github.com/sam1el/snyk-api. Upon maturity and official adoption, it will be migrated to github.com/snyk/snyk-api.

• 🛡️ Full Coverage - 196 operations across REST (103) and v1 (93)
• 🎯 Type-Safe + Manual - Generated clients where possible, hand-tuned wrappers for complex REST discriminators
• 🔄 Rate Limiting & Retries - Token bucket with exponential backoff/jitter
• 🎨 Flexible Output - JSON, YAML, and table views
• 🧩 Templating & Filters - Go templates (--template) and jq-style filters (--jq)
• 🔌 Framework Integration - Built on go-application-framework (auth, config)
• 🌍 Multi-Region Support - All Snyk regional endpoints
• 📦 Library + CLI - Importable Go SDK and full-featured Cobra CLI
• 🔐 Profiles & Auth - Profile-aware config file, auth/login helpers, shell completions

📦 Installation

CLI Installation

go install github.com/sam1el/snyk-api/cmd/snyk-api@latest

Library Installation

go get github.com/sam1el/snyk-api

🚀 Quick Start

CLI Usage

REST examples:

# Set your Snyk API token
export SNYK_TOKEN=your-snyk-token-here

# List organizations (REST)
snyk-api rest orgs list --limit 20

# Get org details (REST, YAML output)
snyk-api rest orgs get <org-id> --output yaml

# List group orgs (REST)
snyk-api rest groups orgs list --group-id <group-id>

# List projects in an org (REST)
snyk-api rest orgs projects list --org-id <org-id> --limit 50

# Export issues (REST)
snyk-api rest orgs export create --org-id <org-id>

v1 examples:

# Aggregated issues (v1)
snyk-api v1 projects aggregated-issues --org-id <org-id> --project-id <project-id> --severity critical,high

# Dependency graph (v1)
snyk-api v1 projects dep-graph --org-id <org-id> --project-id <project-id>

# Webhooks (v1)
snyk-api v1 webhooks list --org-id <org-id>

Auth, profiles, config:

# Login and store token in a profile
snyk-api auth login --profile prod

# Switch profile
snyk-api config use-profile prod

# Set defaults (api_url, org, output) for a profile
snyk-api config set api_url https://api.eu.snyk.io --profile prod
snyk-api config set org_id <org-id> --profile prod
snyk-api config set output yaml --profile prod

# Check status
snyk-api auth status --profile prod

Library Usage

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/sam1el/snyk-api/pkg/apiclients/orgs"
    "github.com/sam1el/snyk-api/pkg/apiclients/projects"
    "github.com/sam1el/snyk-api/pkg/client"
)

func main() {
    ctx := context.Background()

    // Create base client (uses SNYK_TOKEN from environment)
    baseClient, err := client.New(ctx)
    if err != nil {
        log.Fatal(err)
    }
    defer baseClient.Close()

    // List organizations
    orgsClient := orgs.NewOrgsClient(baseClient)
    limit := 10
    orgsList, err := orgsClient.ListOrganizations(ctx, &orgs.ListOrganizationsParams{
        Limit: &limit,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, org := range orgsList.Data {
        fmt.Printf("Org: %s (%s)\n", org.Attributes.Name, org.Id)
    }

    // List projects in first organization
    if len(orgsList.Data) > 0 {
        orgID := orgsList.Data[0].Id.String()
        projectsClient := projects.NewProjectsClient(baseClient)

        projectsList, err := projectsClient.ListProjects(ctx, orgID, &projects.ListProjectsParams{
            Limit: &limit,
        })
        if err != nil {
            log.Fatal(err)
        }

        for _, project := range projectsList.Data {
            fmt.Printf("  Project: %s (%s)\n", project.Attributes.Name, project.Attributes.Type)
        }
    }
}

Advanced Client Configuration

// Custom configuration
baseClient, err := client.New(ctx,
    client.WithVersion(client.APIVersion("2024-04-22")),           // Specific API version
    client.WithBaseURL("https://api.snyk.io", "https://api.snyk.io/rest"), // Custom endpoint
    client.WithRateLimitConfig(ratelimit.Config{
        BurstSize:      20,
        Period:         time.Second,
        MaxRetries:     10,
        RetryBaseDelay: 200 * time.Millisecond,
        RetryMaxDelay:  10 * time.Second,
    }),
)

🎯 Command Overview

snyk-api --help                  # Top-level help
snyk-api version                 # Version info

# Full REST API (103 ops)
snyk-api rest --help
snyk-api rest orgs list
snyk-api rest orgs memberships list --org-id <org>
snyk-api rest groups orgs list --group-id <group>
snyk-api rest tenants broker-deployments list
snyk-api rest self apps list

# Full v1 API (93 ops)
snyk-api v1 --help
snyk-api v1 projects aggregated-issues --org-id <org> --project-id <proj>
snyk-api v1 testing test-npm --package express@4.18.2
snyk-api v1 reporting latest-issues --org-id <org>
snyk-api v1 integrations list --org-id <org>

# Legacy generated helpers (aliases)
snyk-api orgs list
snyk-api projects list --org-id <org>

# Auth, config, completion
snyk-api auth login --profile default
snyk-api auth status --profile prod
snyk-api config list
snyk-api completion bash

# Context caching
snyk-api context set --org-id <org> --group-id <group> --project-id <proj>
snyk-api context show

# Template / jq
snyk-api rest orgs list --limit 5 --jq '.data[].attributes.name'
snyk-api rest orgs list --limit 1 --template '{{ (index .data 0).attributes.name }}'

Global Flags

--output, -o       Output format: json, yaml, table (default: json)
--api-url          Override Snyk API URL
--api-version      Snyk API version (default: latest GA)
--debug            Enable debug logging
--template         Go text/template to render the result (overrides format)
--jq               jq-style filter applied before formatting

⚙️ Configuration

Environment Variables

Config File & Precedence

• Config file: ~/.config/snyk-api/config.yaml
• Profiles supported: profiles.<name>.* (token, api_url, rest_api_url, api_version, org_id, group_id, project_id, output, page_size, debug)
• Precedence: CLI flags > env vars > config file > built-in defaults

Releases

• Built with GoReleaser. To produce local artifacts: goreleaser release --snapshot --clean.

API Versioning

Snyk's REST API uses date-based versioning. Specify versions per request:

# Use specific API version
snyk-api orgs list --api-version 2024-04-22

# Use beta version
snyk-api orgs list --api-version 2025-11-05~beta

# Use experimental version
snyk-api orgs list --api-version 2025-11-05~experimental

In Go code:

// Use default latest GA version
client.New(ctx)

// Use specific version
client.New(ctx, client.WithVersion(client.Version20240422))

// Use beta
client.New(ctx, client.WithVersion(client.DefaultAPIVersion.Beta()))

See API_VERSIONING.md for details.

📊 Project Status

Current: Full API coverage (REST 103 ops + v1 93 ops = 196 total)

🏗️ Architecture

Built on proven patterns from Snyk's go-application-framework:

OpenAPI Spec → oapi-codegen → Generated Client (where possible) → Wrapper → CLI
Manual REST/v1 Client → Wrapper → CLI
                                    ↓
                              Base Client (rate limit, retry, auth)
                                    ↓
                              Snyk REST + v1 APIs

Project Structure

snyk-api/
├── cmd/
│   └── snyk-api/              # CLI entry point
├── pkg/
│   ├── client/                # Base HTTP client with rate limiting
│   ├── apiclients/
│   │   ├── orgs/              # Generated REST clients (sample)
│   │   ├── rest/              # Manual REST clients (full coverage)
│   │   └── v1/                # Manual v1 clients (full coverage)
│   └── config/               # Configuration management
├── internal/
│   ├── commands/             # Cobra CLI commands
│   ├── output/               # Output formatters
│   └── ratelimit/            # Rate limiting implementation
├── .github/
│   ├── api-ref/              # OpenAPI specifications
│   └── workflows/            # CI/CD pipelines
└── docs/
    └── planning/             # Architecture docs

🛠️ Development

Prerequisites

• Go 1.24 or later
• Make
• golangci-lint
• oapi-codegen

Setup

# Clone repository
git clone https://github.com/sam1el/snyk-api.git
cd snyk-api

# Install development tools
make install-tools

# Run tests
make test

# Run linters
make lint

# Build CLI
make build

# Run all checks
make all

Make Targets

make help              # Show all available targets
make build             # Build the CLI binary
make test              # Run tests with coverage
make lint              # Run golangci-lint
make fmt               # Format code (gofmt + gofmt -s)
make vet               # Run go vet
make generate          # Generate API clients from OpenAPI specs
make pull-specs        # Pull latest OpenAPI specifications
make clean             # Clean build artifacts
make dev               # Run fmt + vet + lint + test

Adding New API Domains

See CONTRIBUTING.md for detailed instructions on adding new API domains.

Quick overview:

1. Create minimal OpenAPI spec in .github/api-ref/rest/
2. Add oapi-codegen.yaml config
3. Generate client: make generate
4. Create wrapper client in pkg/apiclients/<domain>/
5. Add CLI commands in internal/commands/
6. Add tests

📚 Documentation

• Planning Documents - Architecture decisions and analysis
• API Versioning Strategy
• Framework Analysis
• Phase Completion Reports
• Contributing Guide

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linters (make dev)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

🔗 Related Projects

• go-application-framework - Core Snyk framework
• cli - Official Snyk CLI
• snyk-request-manager-go - Rate-limited request manager

📄 License

Apache-2.0 - see LICENSE for details.

💬 Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Documentation
• 💬 Discussions

Built with ❤️ for the Snyk community