@allthingsapi/ata-cli v0.1.25

All Things API CLI

A professional command-line interface (CLI) for API testing, validation, and management. Enables developers to validate OpenAPI specifications, lint API designs, and manage API workflows directly from the terminal with an efficient, developer-friendly experience.

🚀 Installation

npm install -g @allthingsapi/ata-cli

✨ Features

ATA CLI brings powerful, modern API management to your terminal:

• Authenticate securely with your AllThingsAPI account (ata login).
• List and inspect APIs for any team and project, including versions, creators, and descriptions.
• Filter APIs by team and project for focused workflows.
• View current user and session information at any time (ata whoami).
• Manage your session: log out instantly (ata logout).
• Seamless updates: keep your CLI up to date with a single command (ata update).
• Ready for automation: designed for CI/CD, scripting, and integration into developer workflows.
• Export OpenAPI Specs: Download OpenAPI specs for any version package in JSON or YAML format for use in tools like Postman, Swagger, or CI/CD.
• Lint OpenAPI Specs: Validate your API specifications against industry best practices using Spectral rules.
• Multiple Policy Support: Apply different rulesets to ensure API quality and consistency.
• Team Management: View teams you are assigned to and explore their business applications.
• Extensible foundation: future support for API testing, automation, and export/import workflows.

📖 Usage

Note: You must be logged in (ata login) before using any API commands.

Authenticate

ata login

Log in to your ATA account and save your session securely.

Show Current User

ata whoami

Display the currently logged-in user's name and email.

List APIs

ata api list --team <TEAM_ID> --project <PROJECT_ID>

List all APIs for a specific team and project, including their versions, creator, description, and type.

Arguments

Example

ata api list --team 6800dfb0d0f8ec7048505892 --project 6800dfb250a4f6540b38913b

Example Output

┌────────────────────────────────────────────────────────────
│ Name: Customer Management API
│ Description: -
│ Application Type: API_APPLICATION
│ Created By: Shoaib Mehedi
│ Versions:
│   • 1.0 (ub3vc171z): 68275ec4094dd3ec1b66cc85 [DRAFT]
│   • 2.0 (wzuwzztw8): 6828e0577e417388e07af6f2 [DRAFT]
└────────────────────────────────────────────────────────────

Error Handling

• If either --team or --project is missing, the CLI will show an error and exit.
• You must be logged in (ata login) before using API commands.

Lint OpenAPI Spec

Validate and lint your OpenAPI specifications against standard and custom policy rules using the Spectral CLI. Supports both remote API specs and local OpenAPI files in JSON and YAML formats.

Usage

# Lint a remote API specification
ata api lint --package <PACKAGE_ID> --policy <POLICY_ID|default>

# Lint a local OpenAPI file
ata api lint --file <FILE_PATH> --policy <POLICY_ID|default>

Arguments

Examples

# Validate a remote API spec against standard OpenAPI rules
ata api lint --package 68275ec4094dd3ec1b66cc85 --policy default

# Validate a remote API spec against a specific custom policy
ata api lint --package 68275ec4094dd3ec1b66cc85 --policy 6800dfbffee72cc9c148b38f

# Validate a local JSON file against standard OpenAPI rules
ata api lint --file ./specs/my-api.json --policy default

# Validate a local YAML file against a specific custom policy
ata api lint --file ./specs/petstore.yaml --policy 6800dfbffee72cc9c148b38f

Sample Files

The CLI package includes sample OpenAPI files in the test-specs directory that you can use for testing and reference:

• test-specs/sample-openapi.json - A valid OpenAPI specification
• test-specs/flawed-openapi.json - An OpenAPI specification with intentional issues for testing linting functionality
• test-specs/.spectral.yaml - A sample Spectral configuration file

You can use these files to experiment with the linting functionality:

# Test linting with the included sample files
ata api lint --file ./test-specs/flawed-openapi.json --policy default

Example Output

┌──────────────────────────────────────────────────┐
│ OpenAPI Specification Lint Results               │
├──────────────────────────────────────────────────┤
│ Package ID: 68275ec4094dd3ec1b66cc85              │
│ Policy:     6800dfbffee72cc9c148b38f              │
├──────────────────────────────────────────────────┤
│ Summary                                          │
│   • Total Issues: 1                               │
│   • Errors:       1                               │
│   • Warnings:     0                               │
│   • Info:         0                               │
├──────────────────────────────────────────────────┤
│ Errors                                           │
├──────────────────────────────────────────────────┤
│❌ [6800dfbffee72cc9c148b38f-rule] API must        │
│define security schemes                           │
│   components                                     │
│   at line 130                                    │
│                                                  │
├──────────────────────────────────────────────────┤
│ ❌ Failed: API specification has errors           │
└──────────────────────────────────────────────────┘

Features

• Dual Validation Modes:

  • Default Mode: Standard OpenAPI (OAS3) validation rules
  • Custom Policy Mode: Organization-specific validation rules

• Policy-Specific Rules: Different policies validate different aspects of the API:

  • Security policies check for proper security definitions
  • Response policies validate consistent response structures
  • Custom policies for organization-specific requirements

• Professional Output:

  • Clear categorization of issues by severity
  • Detailed location information with precise line numbers
  • Well-formatted, boxed output for readability
  • Path information for pinpointing exact issue locations
  • Color-coded pass/fail indicators

• Advanced Implementation:

  • Powered by Spectral CLI for reliable validation
  • Temporary file management for efficient processing
  • Custom rules transformation for policy-specific validation

Error Handling

• Missing package ID or file path parameters trigger clear error messages
• Either --package or --file must be provided (but not both)
• Authentication failures include instructions for login
• Network issues provide actionable troubleshooting steps
• Invalid OpenAPI specs show detailed validation errors
• File access and parsing errors include specific error messages
• Debug mode shows additional implementation details (set DEBUG=1)
• Non-zero exit code returned when API specification has errors

Technical Details

• Based on @stoplight/spectral-cli v6.x
• Creates isolated rulesets for each policy ID
• Policies are fetched and transformed into Spectral-compatible format
• Temporary files are automatically cleaned up after execution
• Supports JSON and YAML format detection and parsing
• File format is automatically detected based on extension or content
• Uses js-yaml for YAML parsing and @stoplight/json for JSON parsing
• Properly validates both remote and local OpenAPI specifications

Export OpenAPI Spec

Export the OpenAPI specification for a version package in JSON or YAML format.

Usage

ata api get --package <PACKAGE_ID> --output <openapi.json|openapi.yaml|openapi.yml>

Arguments

Supported Formats

• .json (default): OpenAPI JSON
• .yaml or .yml: OpenAPI YAML

Examples

ata api get --package 68275ec4094dd3ec1b66cc85 --output openapi.json   # JSON
ata api get --package 68275ec4094dd3ec1b66cc85 --output openapi.yaml   # YAML
ata api get --package 68275ec4094dd3ec1b66cc85 --output openapi.yml    # YAML

If --output is not specified, the CLI will default to openapi-<PACKAGE_ID>.json.

Error Handling

• If --package is missing, the CLI will show an error and exit.
• If the OpenAPI spec is not found, you will see a clear error message.
• You must be logged in (ata login) before using api get.

Update API Specification

Update an OpenAPI specification for a package by uploading content from a local file.

Usage

ata api update --package <PACKAGE_ID> --file <FILE_PATH>

Options

Example

ata api update --package abc123 --file ./openapi.json

Features

• Supports JSON and YAML formats (.json, .yml, .yaml)
• Secure authentication using your ATA credentials
• Clear success and error messaging

You must be logged in (ata login) before using this command.

🧪 Run API Test Collections

Run all requests in a collection and view a professional, Postman-like summary of test results. Optionally, save a detailed report to a local file for CI/CD, auditing, or sharing.

Usage

ata run --collection <COLLECTION_ID> [--env <ENV_ID>] [--genv <GLOBAL_ID>] [--report <report.json>]
ata run --collection <COLLECTION_ID> --env <ENV_ID> --genv <GLOBAL_ID> -r <report.json>

Arguments & Flags

Example

# Run a collection with environment and global context
ata run --collection 68078d82e83b814cd6fbec6b --env 6800dfbcd9ba2022c515beaf --genv 6800dfbcd9ba2022c515beaf --report results.json

# Run a collection without environment/global context
ata run --collection 68078d82e83b814cd6fbec6b

Note: --env and --genv are mapped internally to the API's envId and globalId parameters for flexible environment and global context support. They are optional; omit them to use default API behavior.

Output

• Console:
  • Each request is shown with its name, ID, pass/fail status, and test results.
  • A visually distinct summary table appears at the end, showing total, passed, and failed requests, with color and bold formatting for clarity.
• Report File (JSON):
  • If --report or -r is provided, a machine-readable JSON file is saved with the full run details.

Example Console Output

Found 6 requests in collection.
──────────────────────────────────────────────────
Request: New Request [682b01c3f80b20dd07da3804]
Status: ✔ PASSED
──────────────────────────────────────────────────
Request: update [68078d82e83b814cd6fbec6c]
  ✓ Check if request method is PUT
  ✗ Verify status code is 422 for invalid PUT request: Expected 200 to equal 422
  ✗ Check response body is empty: Expected [object Object] to be empty
  ✓ Verify Content-Type header in response
  ✗ Response time is less than 300ms: Expected 469 to be below 300
  ✓ Verify status code for DELETE request returns 200
  ✗ Verify response body is empty for DELETE request: Expected [object Object] to be empty
  ✗ Verify Content-Type header in response: ata.expect(...).to.contain is not a function
  ✗ Verify response time is less than 300ms for DELETE request: Expected 469 to be below 300
  ✗ Verify DELETE request does not return a body: ata.response.body is not a function
Status: ✗ FAILED
──────────────────────────────────────────────────
Request: patch [68078d82e83b814cd6fbec6d]
  ✓ Verify request method is PATCH
  ✓ Verify response status code is 200
  ✓ Verify Content-Type header is present
  ✓ Verify response time is less than 300ms
Status: ✔ PASSED
──────────────────────────────────────────────────
Request: delete [68078d82e83b814cd6fbec6e]
Status: ✔ PASSED
──────────────────────────────────────────────────
Request: getlist [68078d82e83b814cd6fbec6f]
Status: ✔ PASSED
──────────────────────────────────────────────────
Request: add [68078d82e83b814cd6fbec70]
  ✓ Request method should be POST
  ✗ Validate response status code for invalid data: Expected 201 to equal 422
  ✗ Check response body is empty: Expected [object Object] to be empty
  ✓ Ensure Content-Type header is present in response
  ✗ Response time is less than 300ms: Expected 760 to be below 300
Status: ✗ FAILED

=============================================
         Collection Run Summary         
=============================================
Total Requests:    6
Passed:            4
Failed:            2

   4 PASSED, 2 FAILED

=============================================
Report saved to results.json

Example Report File (JSON)

{
  "collectionId": "68078d82e83b814cd6fbec6b",
  "runAt": "2025-05-18T20:52:41.099Z",
  "summary": {
    "total": 5,
    "passed": 0,
    "failed": 5
  },
  "results": [
    {
      "name": "update",
      "id": "68078d82e83b814cd6fbec6c",
      "status": "FAILED",
      "testResults": [
        { "name": "Check if request method is PUT", "success": false, "error": "ata.request.method is not a function" }
      ],
      "error": "Test Failures: Check if request method is PUT: ata.request.method is not a function"
    },
    ...
  ]
}

Error Handling

• If the collection ID is missing, the CLI will show an error and exit.
• If a request fails or returns an unrecognized response, it is marked as FAILED in the summary and report.
• If the report file cannot be written, a clear error message is shown.

Competitive Positioning

• The ata run command provides a professional, Postman-like summary and reporting experience—ideal for automated testing, CI/CD, and developer workflows.
• Output is clear, color-coded, and easy to scan for quick feedback or auditing.

🤝 Team Commands

List Teams

ata team list

List all teams assigned to the current user, including team names, IDs, descriptions, and member counts.

Example Output

==============================================
         Available Teams         
==============================================
──────────────────────────────────────────────
Team: Backend Developers [6848011ff1118197c2bf3dd4]
Created: 6/10/2025, 9:55:44 AM
Description: Core development team for API services
Members: 8
Alias: be-dev
──────────────────────────────────────────────

✓ 3 teams retrieved successfully.

List Business Applications for a Team

ata team business-apps <TEAM_ID>

Display all business applications associated with a specific team, including detailed information about each application.

Arguments

Example

ata team business-apps 6848011ff1118197c2bf3dd4

Example Output

=======================================================
         Business Applications for Team         
=======================================================
──────────────────────────────────────────────────────────
Title: Backend Developers [68480147654d33540dea419f]
Created: 6/10/2025, 9:56:23 AM
Description: 
Type: PUBLIC
Category: TEAM
──────────────────────────────────────────────────────────
Title: Team Business Application [684801208724f47ae6fcbc73]
Created: 6/10/2025, 9:55:44 AM
Description: Default Project
Type: PUBLIC
Category: TEAM
Robustness Tests: 9
Security Tests: 19
──────────────────────────────────────────────────────────

✓ 2 business application(s) retrieved successfully.

🛠 Other Commands

• ata logout — Log out and remove stored login information
• ata update — Update ATA CLI to the latest version

🤝 Contributing

Contributions, issues, and feature requests are welcome! Please see the issues page or submit a pull request.

📬 Support

For help or questions, please visit the AllThingsAPI website or contact support.

© 2025 AllThingsAPI