Getting Started with APIMux CLI: Authentication & First API Call

This tutorial walks you through installing the APIMux CLI, authenticating your device, and making your first API call. By the end, you'll understand how to explore available capabilities, interpret responses, and manage your API usage.

Prerequisites

• macOS, Linux, or Windows with WSL
• A web browser for device authentication
• An APIMux account (sign up at the APIMux web app)

Step 1: Install the CLI

The APIMux CLI is distributed as a single binary from GitHub releases:

curl -fsSL https://github.com/reorc/apimux-cli/releases/latest/download/install.sh | sh

This script:

• Detects your OS and architecture
• Downloads the appropriate binary
• Installs it to ~/.local/bin/apimux
• Adds the binary to your PATH

Verify the installation:

apimux --version

Step 2: Authenticate with Device Flow

APIMux uses device-flow authentication, which means you approve the CLI login in your browser without entering credentials in the terminal.

Start the authentication flow:

apimux auth login

You'll see output like:

Visit: https://<your-apimux-web-host>/auth/cli?user_code=ABCD-1234
Code: ABCD-1234
Waiting for authorization...

What happens next:

1. The CLI displays a verification URL
2. You open the URL in your browser
3. You log in to your APIMux account (if not already logged in)
4. You review the device information and approve the request
5. The CLI receives an API key and stores it locally

Once approved, you'll see:

Authorized. API key saved to ~/.apimux/config.json

Your CLI is now authenticated and ready to make API calls.

Step 3: Explore Available Capabilities

Before making API calls, let's see what's available. APIMux provides 38 capabilities across 9 data sources:

• Amazon (14 capabilities): Product search, reviews, sales data, keyword research
• TikTok (4 capabilities): Video search, comments, shop products
• Reddit (4 capabilities): Post search, subreddit feeds, comments
• Meta Ads (2 capabilities): Ad library search, ad details
• Google Ads (3 capabilities): Ad intelligence
• Google Trends (1 capability): Search trends
• Douyin (4 capabilities): Chinese TikTok data
• Xiaohongshu (3 capabilities): Chinese social commerce
• TrendCloud (3 capabilities): Trend analysis

To see detailed parameters for a specific capability:

apimux schema show amazon.search_products

This shows:

• Required and optional parameters
• Parameter types and constraints
• Response schema

Step 4: Make Your First API Call

Let's search for products on Amazon:

apimux amazon search_products \
  --q "wireless headphones" \
  --page 1

Understanding the Response:

By default, APIMux returns compact output—a streamlined JSON format optimized for AI agents. The exact structure depends on the capability, but it removes verbose metadata and uses consistent field naming.

To see the full response with metadata (useful for debugging):

apimux amazon search_products \
  --q "wireless headphones" \
  --page 1 \
  --output pretty

Available output formats:

• compact (default): Minimal JSON
• pretty: Formatted JSON with metadata
• data: Just the data array
• data-pretty: Formatted data array

Use --debug to see request/response details for troubleshooting.

Step 5: Track Your Usage

Each API call consumes credits. You can view your usage and credit balance in the APIMux web app under Settings or Admin (if you're an admin).

Credit Costs:

Different capabilities have different costs based on complexity:

• Simple lookups: 1-2 credits
• Search operations: 2-5 credits
• Bulk data retrieval: 5-10 credits

Step 6: Common CLI Patterns

Pipe output to jq for filtering:

apimux amazon search_products --q "laptop" --page 1 \
  | jq '.[] | select(.rating > 4.5) | {title, price, rating}'

Save output to a file:

apimux tiktok search_videos --keyword "cooking" --count 50 > tiktok_cooking.json

Use in scripts:

#!/bin/bash
PRODUCTS=$(apimux amazon search_products --q "$1" --page 1)
echo "$PRODUCTS" | jq '.[0].title'

Step 7: Shell Completion (Optional)

Enable shell completion for faster command entry:

# For bash
apimux completion bash > ~/.apimux-completion.bash
echo 'source ~/.apimux-completion.bash' >> ~/.bashrc

# For zsh
apimux completion zsh > ~/.apimux-completion.zsh
echo 'source ~/.apimux-completion.zsh' >> ~/.zshrc

Reload your shell, and you can now tab-complete commands, sources, and capabilities.

Next Steps

Now that you're set up, explore more capabilities:

• E-commerce research: apimux amazon get_product --asin B08PZHYWJS
• Social trends: apimux tiktok search_videos --keyword "viral" --count 20
• Ad intelligence: apimux meta_ads search_ads --q "fitness"
• Community insights: apimux reddit search --query "product recommendations"

Visit the documentation for complete API reference, or check out our next tutorial on using APIMux for Amazon product research.

Troubleshooting

Authentication fails:

• Ensure you're logged in to the APIMux web app
• Check that the user code matches what's shown in the browser
• Try starting a new auth flow with apimux auth login

API calls return errors:

• Check parameter syntax: apimux schema show <source>.<capability>
• Review error messages—they include specific guidance
• Verify you're using the correct parameter names (e.g., --q not --query for most searches)

CLI not found after installation:

• Restart your terminal to reload PATH
• Manually add ~/.local/bin to your PATH if needed:

  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

For additional support, reach out at [email protected].