Theneo CLI

What is Theneo CLI?

Theneo CLI is a command-line interface tool that enables you to manage the Theneo platform directly from your terminal. It provides a streamlined workflow for creating, updating, publishing, and managing API documentation without requiring a web browser interface.

Key Features

• Create and manage API documentation projects - Build comprehensive API docs from the command line
• Import API specifications from multiple sources - Support for OpenAPI, Postman, files, and URLs
• Publish documentation automatically - Make documentation available to your audience instantly
• Manage project versions and versions - Track API evolution with semantic versioning
• Export documentation in multiple formats - Markdown, OpenAPI, and more
• Manage workspaces and collaborate with teams - Organize documentation across teams
• Work with tabs for multi-API documentation - Document multiple related APIs in one project
• Support for environment-specific configurations - Handle different deployment environments

System Requirements

• Node.js 12.x or higher
• npm (Node Package Manager)
• Git (for repository operations)
• Access to Theneo platform account

Installation & Setup

Installation Methods

Global Installation (Recommended)

Install Theneo CLI globally to use it from any directory:

 
npm install -g @theneo/cli@latest

This command installs the latest version of Theneo CLI globally on your machine, making it accessible from any terminal session.

Verifying Installation

To verify the CLI is installed correctly:

 
theneo -V

This command displays the installed version number. If successful, you can proceed with authentication.

Authentication & Configuration

Authentication Methods

Token-Based Login

Login with an API token

 
theneo login --token <theneo-api-key>

Project Management

Creating Projects

Standard Project Creation:

 
theneo project create

Creating from OpenAPI Specification

Import from a local OpenAPI file:

 
theneo project create \
  --name api-documentation \
  --file ./examples/openapi-spec.json \
  --generate-description overwrite \
  --publish \
  --public

Creating from URL

Import directly from a remote API specification:

 
theneo project create \
  --name api-documentation \
  --link https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/uspto.json \
  --publish \
  --public

Creating from Postman Collections

Import one or multiple Postman collections:

 
theneo project create \
  --name api-documentation \
  --postman-api-key <key> \
  --postman-collection <id-1> \
  --postman-collection <id-2>

Project Creation Options

Importing into Existing Projects

Update an existing project with new API specifications:

 
theneo project import \
  --project <project-slug> \
  --file <file> \
  --publish

Import Type Options

Different import strategies for handling specification updates:

• endpoints - Update only endpoint definitions
• overwrite - Replace entire documentation
• append - Add new content without removing existing
• merge - Intelligently merge old and new specifications (preserves customizations)

Merge with Parameter Preservation

When using merge import type, preserve custom parameter descriptions:

 
theneo project import \
  --project <project-slug> \
  --workspace <workspace-slug> \
  --projectVersion <version-slug> \
  --publish \
  --file ./api-spec.json \
  --import-type merge \
  --keepOldParameterDescription \
  --keepOldSectionDescription

Publishing Projects

Publish a project to make it available:

 
theneo project publish --project <project-slug>

This makes your documentation publicly accessible or available to your team depending on the privacy settings.

Deleting Projects

Remove a project permanently:

 
theneo project delete --project <project-slug>

Version Management

About Versions

Versions allow you to maintain multiple iterations of your API documentation independently. Each version can have its own endpoints, descriptions, and publishing status. This is essential for managing API evolution.

Listing Versions

View all versions of a project:

 
theneo version list \
  --project <project-slug> \
  --workspace <workspace-slug>

Creating Versions

Create a new project version:

 
theneo version create \
  --name v2.0 \
  --project <project-slug> \
  --workspace <workspace-slug>

Duplicate Previous Version

Create a version by duplicating content from an existing version:

 
theneo version create \
  --name v2.0 \
  --project <project-slug> \
  --workspace <workspace-slug> \
  --previousVersion v1.0

This is useful when making a new major version where you want to start with the previous version's content.

Deleting Versions

Remove a specific version:

 
theneo version delete \
  --project <project-slug> \
  --workspace <workspace-slug> \
  --version <version-slug>

Managing Changelog Subscribers

Add email subscribers to receive changelog notifications:

 
theneo version add-subscriber \
  --project <project-slug> \
  --workspace <workspace-slug> \
  --projectVersion <version-slug> \
  --email user@example.com

Multiple subscribers: Run the command multiple times with different email addresses to add multiple subscribers.

Data Import & Export

Exporting Documentation

Export as Markdown

Export project documentation in Markdown format:

 
theneo export \
  --project <project-slug> \
  --projectVersion <version-slug> \
  --workspace <workspace-slug> \
  --dir ./docs

Benefits:

• Create a structured Markdown directory with your documentation
• Version control your docs using Git
• Enable team collaboration via pull requests
• Maintains consistency with code repository

Export as OpenAPI Specification

Export your Theneo documentation back to OpenAPI format:

 
theneo export \
  --openapi \
  --format json \
  --project <project-slug> \
  --projectVersion <version-slug> \
  --workspace <workspace-slug> \
  --dir ./spec

Supported formats:

JSON export:

 
theneo export --openapi --format json --project <slug> --dir ./spec

YAML export:

 
theneo export --openapi --format yaml --project <slug> --dir ./spec

Importing from Markdown

Create a new project from Markdown files:

 
theneo create \
  --dir ./docs \
  --name my-api \
  --workspace <workspace-slug>

Updating from Markdown

Update an existing project from Markdown files:

 
theneo import \
  --project <project-slug> \
  --workspace <workspace-slug> \
  --dir ./docs

Tab Management

Managing Tabs Within Projects

What are Tabs?

Tabs allow you to manage multiple APIs within a single Theneo project. Each tab can have its own API specification and documentation while maintaining a unified project interface.

Use cases for tabs:

• Multiple microservices with related functionality
• Different versions of the same API
• Related but independent APIs under one umbrella
• Breaking down large API documentation into manageable pieces

Export Specific Tab

Export documentation for a specific tab:

 
theneo export \
  --project <project-slug> \
  --projectVersion <version-slug> \
  --workspace <workspace-slug> \
  --tab <tab-slug> \
  --dir ./tab-docs

Export Tab as OpenAPI

Export a tab's API specification:

 
theneo export \
  --openapi \
  --format json \
  --project <project-slug> \
  --projectVersion <version-slug> \
  --workspace <workspace-slug> \
  --tab <tab-slug> \
  --dir ./spec

Import Markdown to Specific Tab

Update a specific tab from Markdown files:

 
theneo import \
  --project <project-slug> \
  --workspace <workspace-slug> \
  --tab <tab-slug> \
  --dir ./docs

Import OpenAPI to Specific Tab

Update a tab's API specification:

 
theneo project import \
  --file ./api-spec.json \
  --project <project-slug> \
  --tab <tab-slug> \
  --publish

Common Tasks Checklist

Troubleshooting

Authentication Issues

If you encounter authentication errors:

1. Verify API key - Ensure your API key is correct and not expired
2. Check environment variable - Verify THENEO_API_KEY is properly set
3. Try fresh login - Re-authenticate: theneo login --token <key>
4. Check account permissions - Verify account role in Theneo web interface
5. Validate workspace access - Ensure you have access to the workspace

Import Errors

When import fails:

1. Validate specification - Ensure API spec follows OpenAPI 3.x format
2. Check file permissions - Verify file paths and read permissions
3. Verify project/workspace - Confirm project and workspace slugs exist
4. Check specification size - Very large specs may require timeout adjustments

Publishing Issues

If publishing fails:

1. Check endpoints - Confirm project contains valid endpoints
2. Review descriptions - Verify descriptions meet any length requirements

Version Management Issues

When working with versions:

1. List versions - Check existing versions: theneo version list --project <slug>
2. Verify slug spelling - Ensure previous version slug is spelled correctly
3. Check permissions - Verify workspace and project ownership

Performance Optimization

• Keep directories clean - Remove unnecessary Markdown files
• Use profiles - Avoid re-authenticating with every command
• Run exports periodically - Create regular backups of your documentation