DEV Community

Allen Tuh
Allen Tuh

Posted on

How to Use Sidekick's Instant Commands from OpenAPI/Postman

#ai #programming #cli #oclif

Sidekick (sdkck) is a CLI companion tool designed for AI agents and developers. One of its most powerful features is the ability to turn any OpenAPI/Swagger spec or Postman collection into executable CLI commands — instantly. No code generation, no SDK wrappers. Just point it at a spec, and every endpoint becomes a command you can run.

This guide walks you through the full workflow: importing specs, calling endpoints, configuring auth, searching commands, and managing your imported APIs.

Prerequisites

Install Sidekick globally via npm:

npm install -g sdkck
Enter fullscreen mode Exit fullscreen mode

Step 1: Import an OpenAPI Spec or Postman Collection

The sdkck openapi import command accepts a URL or a local file path. It parses the spec and registers every operation as a runnable CLI command.

From a URL:

sdkck openapi import https://raw.githubusercontent.com/upstash/context7/refs/heads/master/docs/openapi.json --name context7
Enter fullscreen mode Exit fullscreen mode

The --name flag gives your API a short identifier that becomes the command namespace. If you omit it, Sidekick derives a slug from the spec's title.

You can also configure auth and a custom base URL during import:

sdkck openapi import ./api.yaml --name myapi --auth-type bearer --token sk-... --base-url https://api.example.com
Enter fullscreen mode Exit fullscreen mode

Step 2: List and Call Operations

Once imported, use sdkck <API name> to see all registered operations:

Use --help to see the details how to use an operation

Step 3: Configure Authentication

Most real APIs require authentication. Sidekick supports three auth types, configured once per API so every subsequent command uses it automatically.

Bearer token:

sdkck openapi auth petstore --type bearer --token sk-your-token-here
Enter fullscreen mode Exit fullscreen mode

API key:

sdkck openapi auth myapi --type apikey --api-key mykey123 --api-key-header X-API-Key
Enter fullscreen mode Exit fullscreen mode

Basic auth:

sdkck openapi auth petstore --type basic --username user --password secret
Enter fullscreen mode Exit fullscreen mode

Verify your auth settings:

sdkck openapi auth petstore --show
Enter fullscreen mode Exit fullscreen mode

To remove auth from an API:

sdkck openapi auth petstore --type none
Enter fullscreen mode Exit fullscreen mode

Step 4: Update API Configuration

After importing, you can modify the API's settings without re-importing:

# Change the base URL (e.g., switch from staging to production)
sdkck openapi config petstore --base-url https://api.mypetstore.com/v2

# Rename the API namespace
sdkck openapi config petstore --rename mystore

# Update the display title and description
sdkck openapi config petstore --title "My Petstore" --description "Internal pet store API"
Enter fullscreen mode Exit fullscreen mode

Step 5: Remove an API

When you no longer need an imported API:

sdkck openapi remove context7
Enter fullscreen mode Exit fullscreen mode

This unregisters all the operations associated with that spec.

Setup Permissions

You can lock down agent permissions for safety:

# Allow only read operations
sdkck permission allow "petstore listPets"
sdkck permission allow "petstore getPetById"
sdkck permission disallow "petstore *"

# Export permissions for team sharing
sdkck permission export permissions.json
Enter fullscreen mode Exit fullscreen mode

Quick Reference

Task Command
Import a spec sdkck openapi import <source> --name <name>
List all APIs sdkck openapi list
List operations sdkck <API name> --help
Configure auth sdkck openapi auth <name> --type bearer --token <token>
Update config sdkck openapi config <name> --base-url <url>
Remove an API sdkck openapi remove <name>

Summary

Sidekick's OpenAPI/Postman import feature eliminates the gap between having an API spec and being able to use it. There's no code to write, no SDK to learn. Import the spec, configure auth once, and every endpoint is immediately callable from the command line — by you or by an AI agent. Combined with semantic search and a permission system, it makes any API accessible in seconds.

For more details, visit the Sidekick GitHub repository.

Top comments (0)