SA Procurement Data at Your Terminal

The @tenders-sa-org/cli tool provides terminal access to the Tenders-SA Developer API. It supports every API endpoint as a command, filters tenders and awards by province, category, value, and date range, outputs structured JSON suitable for piping into other tools, and stores credentials locally for persistent sessions.

The CLI is open source under the MIT license and published on npm. The source code is available at github.com/Tenders-SA/cli

.

Installation

Install globally via npm, or run directly without installation using npx:

Copy
1# Install globally (recommended for regular use)
2npm install -g @tenders-sa-org/cli
3
4# Or run without installation
5npx @tenders-sa-org/cli tenders list
BASH

Quick Start

Configure your API key once, then start querying data immediately:

Copy
1# Configure your API key (stored in ~/.tendersa/config.json)
2tendersa config set tsa_prod_your_key
3
4# Check API health
5tendersa meta status
6
7# List open tenders in the Western Cape
8tendersa tenders list --status OPEN --province "Western Cape"
9
10# Get tender details
11tendersa tenders get tender_001
12
13# AI-powered semantic search
14tendersa tenders search "road construction"
15
16// ... (truncated)
Show More (5 more lines)
BASH

Configuration

The CLI stores a single configuration file at ~/.tendersa/config.json containing your API key. Manage it through the config command:

Copy
1tendersa config set tsa_prod_your_key    # Save API key
2tendersa config get                        # Show current key (masked)
BASH

The API key is also configurable via the TENDERSA_API_KEY environment variable, which takes precedence over the config file. This is useful for CI/CD environments where you prefer not to write credentials to disk:

Copy
1export TENDERSA_API_KEY=tsa_prod_your_key
2tendersa tenders list --status OPEN
BASH

Command Reference

The CLI mirrors the API resources. Every command outputs JSON to stdout, with errors and progress messages going to stderr.

Tenders

Copy
1# List tenders with filters
2tendersa tenders list \
3  --status OPEN \
4  --province Gauteng \
5  --category Construction \
6  --min-value 1000000 \
7  --closing-after 2026-06-01 \
8  --limit 20 \
9  --sort -closingDate
10
11# Get detailed tender with AI analysis
12tendersa tenders get tender_001
13
14# Semantic search across all tenders
15tendersa tenders search "road construction"
16// ... (truncated)
Show More (5 more lines)
BASH

List filter options:

Awards

Copy
1# List awards with filters
2tendersa awards list \
3  --supplier-name "BuildCorp" \
4  --province Gauteng \
5  --min-amount 500000 \
6  --from 2025-01-01 \
7  --to 2025-12-31 \
8  --limit 50
9
10# Get award details
11tendersa awards get award_001
BASH

Award list options include --supplier-name, --enterprise-type (SMME, QSE, etc.), --bee-level, --province, --category, --min-amount, --max-amount, --from, --to, --page, and --limit.

Companies

Copy
1# Full company intelligence profile (by exact name)
2tendersa companies get "BuildCorp SA"
3
4# Search companies
5tendersa companies search "Construction"
BASH

The company profile includes award history, contract values, enterprise type, BEE level, and compliance data aggregated from public procurement records.

Meta

Copy
1tendersa meta status        # API health and data freshness
2tendersa meta provinces     # Tender counts by province
3tendersa meta categories    # Tender counts by category
4tendersa meta usage         # Your API usage statistics
BASH

Output and Piping

All commands output JSON to stdout, making them safe to pipe into other tools. Error messages go to stderr so they do not interfere with piped data:

Copy
1# Extract tender titles using jq
2tendersa tenders list --status OPEN --limit 5 | jq '.data[].title'
3
4# Count awards by province
5tendersa awards list --limit 100 | jq '[.data[].province] | sort | unique | length'
6
7# Export to file
8tendersa tenders list --status OPEN --limit 1000 > tenders.json
9
10# Pipe through a Python script for custom analysis
11tendersa tenders list --status OPEN | python analyze.py
BASH

CI/CD and Automation

The CLI is designed for use in CI/CD pipelines and automated scripts. Use the TENDERSA_API_KEY environment variable to avoid writing credentials to disk:

Copy
1# GitHub Actions example
2- name: Check tender availability
3  run: |
4    npm install -g @tenders-sa-org/cli
5    export TENDERSA_API_KEY=${{ secrets.TENDERSA_API_KEY }}
6    
7    # Check if there are new tenders in our category
8    COUNT=$(tendersa tenders list \
9      --status OPEN \
10      --category Construction \
11      --closing-after $(date -I) \
12      | jq '.meta.totalCount')
13    
14    echo "Open construction tenders: $COUNT"
15    
16// ... (truncated)
Show More (4 more lines)
BASH

Use Cases

• Quick tender checks: Check active tenders in a province without opening a browser. The CLI loads data in under a second.
• CI/CD integration: Embed tender data into your internal dashboards and reporting pipelines. The CLI's JSON output integrates naturally with GitHub Actions, Jenkins, and similar platforms.
• Market monitoring: Script periodic scans of award activity in your sector. Use cron or scheduled CI jobs to run the CLI and export results.
• Data export: Pipe tender data into CSV, JSON processors, or analysis tools like jq, pandas, or custom scripts.

Links and Resources

The full CLI source code is on GitHub at github.com/Tenders-SA/cli

. The package is published to npm as @tenders-sa-org/cli

. The complete API reference is available at tenders-sa.org/developers/docs

.

The repository includes the full TypeScript source code, the CLI command definitions, and a README with examples for every command. Issues and pull requests are welcome.