SAP HANA CLI

SAP HANA Developer Command Line Interface

[](https://api.reuse.software/info/github.com/SAP-samples/hana-developer-cli-tool-example)

⚠️ Important Notice - Major Updates (Feb/March 2026)

> Version 4.x introduces significant changes including Express 5 migration, refactored database connection handling, and major performance improvements. While we've tested extensively, please be aware of potential issues in your specific environment.

If you encounter problems:

• Report Issues: Please open an issue on our GitHub Issues page with details about your environment and the problem you're experiencing.

• Rollback to Stable Version: If you need to quickly revert to the last stable release before these major changes, you can install version 3.202601.0 (January 2026):

``shell npm install -g hana-cli@3.202601.0 ``

What's Changed: The [change log](CHANGELOG.md) describes all notable changes including Express 5 migration, database connection refactoring, CLI startup performance optimization (60-77% faster), expanded test coverage (85%+ coverage), and the new VitePress documentation site.

📚 Documentation

Complete documentation is available in the [docs/](docs/) folder and organized with VitePress. This README will maintain a high-level overview and quick links to the most important sections of the documentation but over time expect that more and more detailed documentation will be added to the docs folder as the project evolves.

Quick Links:

• [Getting Started](docs/01-getting-started/) - Installation and setup
• [Command Reference](docs/02-commands/) - All 20+ commands with examples
• [Features Guide](docs/03-features/) - CLI, API, MCP, and more
• [API Reference](docs/04-api-reference/) - REST API documentation
• [FAQ](docs/faq.md) - Frequently asked questions
• [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions

Run Documentation Locally

cd docs
npm install
npm run docs:dev
# Open http://localhost:5173

Build For Production

cd docs
npm run docs:build
npm run docs:serve

See [docs/README.md](docs/README.md) for complete documentation setup details.

---

Description

This sample is intended to shown how one could build a developer-centric SAP HANA command line tool, particularly designed to be used when performing local SAP HANA development in non-SAP tooling (like VSCode). It utilizes the default-env.json that is often used in local development for connectivity to a remote SAP HANA DB (although it can of course be used with a local SAP HANA, express edition instance as well). There is no intention to replacing the hdbsql tool as a generic SQL console. Instead this sample will focus on simplifying and grouping common and complex commands that otherwise might a lot of separate scripts.

Introduction Video: https://youtu.be/dvVQfi9Qgog

However the tool isn't limited to only local development. It also works well when developing in the cloud. The hana-cli tool can also run well from a cloud shell in the SAP Business Application Studio, Google Cloud Shell, AWS Cloud9, etc. We can also run against a SAP HANA service for SAP BTP or SAP HANA Cloud instance. This demonstrates that the tool can run just about anywhere you can get a command line that has access to the Node.js Runtime. We can also connect to a remote HANA instance even if it isn't running in the same cloud environment in which we are performing our development tasks.

Supported Environments

graph TD
    A["SAP HANA CLI Tool"] --> B{Development Environment}
    B --> C["Local Development"]
    B --> D["Cloud Development"]
    
    C --> C1["VSCode"]
    C --> C2["Local SAP HANA Express"]
    C --> C3["Remote SAP HANA"]
    
    D --> D1["SAP Business App Studio"]
    D --> D2["Google Cloud Shell"]
    D --> D3["AWS Cloud9"]
    D --> D4["SAP BTP HANA Service"]
    D --> D5["SAP HANA Cloud"]
    
    style A fill:#0070C0
    style B fill:#FF6B6B
    style C fill:#51CF66
    style D fill:#FFD93D

Running in Cloud Shells Video: https://youtu.be/L7QyVLvAIIQ

Requirements / Download and Installation

If you would rather just access the tool directly, it is now available in npm as well. You can install via:

npm install -g hana-cli

Installation Methods

graph LR
    A["SAP HANA CLI Tool"] --> B{Installation Method}
    
    B --> B1["NPM PackageQuick Install"]
    B1 --> B1a["npm install -g hana-cli"]
    B1a --> B1b["✅ Ready to Use"]
    
    B --> B2["Clone & BuildFrom Source"]
    B2 --> B2a["Clone Repositoryfrom GitHub"]
    B2a --> B2b["Run npm install"]
    B2b --> B2c["Run npm link"]
    B2c --> B2d["✅ Ready to Use"]
    
    style B1 fill:#0070C0,color:#fff
    style B2 fill:#FF6B6B,color:#fff
    style B1b fill:#51CF66,color:#fff
    style B2d fill:#51CF66,color:#fff

Otherwise you can also run it from the sources as described here:

• Install Node.js version 20.19.0 or later on your development machine https://nodejs.org/en/download/

• Clone the repository from https://github.com/SAP-samples/hana-developer-cli-tool-example

git clone https://github.com/SAP-samples/hana-developer-cli-tool-example

• Run NPM install from the root of the hana-developer-cli-tool-example project you just cloned to download dependencies

npm install

• Run NPM link from the cloned project root to make the hana-cli command available from everywhere https://docs.npmjs.com/cli/link

npm link

[](https://asciinema.org/a/301560)

BTP CLI Installation

The hana-cli tool includes several commands that interact with SAP Business Technology Platform (BTP) services. All BTP-related functionality in this tool relies on the SAP BTP Command Line Interface (btp CLI) being installed and available in your system's PATH.

About the BTP CLI

The btp CLI is SAP's official command-line tool for managing resources and services on the SAP Business Technology Platform. It provides capabilities for managing global accounts, directories, subaccounts, entitlements, service instances, and more. The hana-cli tool wraps and extends many of these capabilities with developer-friendly commands.

Installing the BTP CLI with install-btp.sh

For Linux and macOS users, this repository includes a convenient installation script [install-btp.sh](scripts/install-btp.sh) that automates the installation of the BTP CLI.

The script performs the following actions:

1. Downloads the latest BTP CLI installer from the SAP Development Tools download page
2. Makes the installer executable and runs it with automatic confirmation
3. Configures shell aliases for easier BTP CLI usage
4. Adds the BTP CLI binary location to your PATH

To use the installation script:

chmod +x scripts/install-btp.sh
./scripts/install-btp.sh

After running the script, you may need to restart your terminal or run source ~/.bashrc to apply the PATH changes.

Note: Windows users should download the BTP CLI from the SAP Development Tools page and follow the platform-specific instructions there.

Verifying the Installation

Once installed, you can verify the BTP CLI is available by running:

btp --version

You can also use the hana-cli tool itself to check your BTP CLI configuration:

hana-cli btp

This will display your current BTP target information including global account, directory, and subaccount if configured.

Security

This application primarily uses the default-env.json that is often used in local development for connectivity to a remote HANA DB (although it can of course be used with a local SAP HANA, express edition instance as well). For more details on how the default-env.json works, see the readme.md of the @sap/xsenv package or the @sap/hdi-deploy package.

Connection Configuration Resolution Order

The tool doesn't simply look for a default-env.json file in the current directory however. There are numerous options and places it will look for the connection parameters. Here is the order in which it checks:

graph TD
    A["Connection ResolutionStarted"] --> B{Admin ModeEnabled?}
    B -->|YES| B1["Look fordefault-env-admin.json"]
    B -->|NO| C{.cdsrc-private.jsonFound?}
    
    B1 --> B2{Found?}
    B2 -->|YES| Z1["Use Admin Credentials"]
    B2 -->|NO| C
    
    C -->|YES| C1["Use CAP cds bindDynamic Lookup"]
    C -->|NO| D{.env FileFound?}
    
    C1 --> Z2["Secure Lookupfrom CF/K8s"]
    
    D -->|YES| D1{ContainsVCAP_SERVICES?}
    D1 -->|YES| Z3["Use VCAP Services"]
    D1 -->|NO| E
    D -->|NO| E
    
    E{--conn ParameterSpecified?} -->|YES| E1["Look for specifiedconnection file"]
    E1 --> E2{Local orHome Found?}
    E2 -->|YES| Z4["Use Specified File"]
    E2 -->|NO| F
    E -->|NO| F
    
    F["Look fordefault-env.jsonin current/parent dirs"]
    F --> G{Found?}
    G -->|YES| Z5["Use default-env.json"]
    G -->|NO| H["Last Resort:Look for default.jsonin HOME/.hana-cli/"]
    
    H --> I{Found?}
    I -->|YES| Z6["Use default.json"]
    I -->|NO| Z7["❌ No ConnectionConfiguration Found"]
    
    style Z1 fill:#51CF66
    style Z2 fill:#51CF66
    style Z3 fill:#51CF66
    style Z4 fill:#51CF66
    style Z5 fill:#51CF66
    style Z6 fill:#51CF66
    style Z7 fill:#FF6B6B

• First we look for the Admin option and use a default-env-admin.json - this overrides all other parameters
• If no admin option or if there was an admin option but no default-env-admin.json could be found in this directory or 5 parent directories, then look for .cdsrc-private.json in this directory or 5 parent directories and use cds bind functionality to lookup the credentials securely. This is the most secure option, but please note: this will make each command take a few seconds longer as credentials are no longer stored locally but looked up from cf or k8s dynamically with each command
• If no .cdsrc-private.json found in this directory or 5 parent directories, then look for a .env file in this directory or up to 5 parent directories
• No .env file found or it doesn't contain a VCAP_SERVICES section, then check to see if the --conn parameter was specified. If so check for that file in the current directory or up to 5 parent directories
• If the file specified via the --conn parameter wasn't found locally then check for it in the ${homedir}/.hana-cli/ folder
• If no specific configuration file was was found then look for a file named default-env.json in the current directory or up to 5 parent directories
• Last resort if nothing has been found up to this point - look for a file named default.json in the ${homedir}/.hana-cli/ folder

Examples

A lot of the functionality of this tool revolves around typical tasks you face while doing HANA database development. For example you might want to get a list of all views in your current schema/container:

C:\github\hana-xsa-opensap-hana7\user_db>hana-cli views
Schema: OPENSAP_HANA_USER, View: *
SCHEMA_NAME        VIEW_NAME                                    VIEW_OID  COMMENTS
-----------------  -------------------------------------------  --------  ------------
OPENSAP_HANA_USER  user.models::USER_DETAILS                    171133    USER_DETAILS
OPENSAP_HANA_USER  user.models::USER_DETAILS/hier/USER_DETAILS  171139    null

Then perhaps you want to inspect a view to see the columns and their data types:

C:\github\hana-xsa-opensap-hana7\user_db>hana-cli view * user.models::USER_DETAILS
Schema: %, View: user.models::USER_DETAILS
{ SCHEMA_NAME: 'OPENSAP_HANA_USER',
  VIEW_NAME: 'user.models::USER_DETAILS',
  VIEW_OID: 171133,
  COMMENTS: 'USER_DETAILS',
  IS_COLUMN_VIEW: 'TRUE',
  VIEW_TYPE: 'CALC',
  HAS_STRUCTURED_PRIVILEGE_CHECK: 'TRUE',
  HAS_PARAMETERS: 'TRUE',
  HAS_CACHE: 'NONE',
  CREATE_TIME: '2019-07-30 13:14:15.594000000' }

SCHEMA_NAME        VIEW_NAME                  VIEW_OID  COLUMN_NAME  POSITION  DATA_TYPE_NAME  OFFSET  LENGTH  SCALE  IS_NULLABLE  DEFAULT_VALUE  CS_DATA_TYPE_NAME  COLUMN_ID  COMMENTS
-----------------  -------------------------  --------  -----------  --------  --------------  ------  ------  -----  -----------  -------------  -----------------  ---------  ---------
OPENSAP_HANA_USER  user.models::USER_DETAILS  171133    EMAIL        1         NVARCHAR        0       255     null   TRUE         null           STRING             171135     Email
OPENSAP_HANA_USER  user.models::USER_DETAILS  171133    FIRSTNAME    2         NVARCHAR        0       40      null   TRUE         null           STRING             171136     FirstName
OPENSAP_HANA_USER  user.models::USER_DETAILS  171133    LASTNAME     3         NVARCHAR        0       40      null   TRUE         null           STRING             171137     LastName
OPENSAP_HANA_USER  user.models::USER_DETAILS  171133    USERID       4         INTEGER         0       10      0      TRUE         null           INT                171138     UserId

But there are multiple output options for inspection. Perhaps you are using Cloud Application Programming Model and need to create a proxy entity in CDS for a view. This tool will read the catalog metadata and convert it to CDS:

C:\github\hana-xsa-opensap-hana7\user_db>hana-cli view OPENSAP_HANA_USER user.models::USER_DETAILS -o cds
Schema: OPENSAP_HANA_USER, View: user.models::USER_DETAILS
@cds.persistence.exists
Entity user_modelsUSER_DETAILS {
 key    "EMAIL": String(255) null  @title: 'EMAIL: Email' ;
key     "FIRSTNAME": String(40) null  @title: 'FIRSTNAME: FirstName' ;
key     "LASTNAME": String(40) null  @title: 'LASTNAME: LastName' ;
key     "USERID": Integer null  @title: 'USERID: UserId' ;
}

Or maybe you are service enabling this view and you want to see it converted to EDMX:

C:\github\hana-xsa-opensap-hana7\user_db>hana-cli view OPENSAP_HANA_USER user.models::USER_DETAILS -o edmx
Schema: OPENSAP_HANA_USER, View: user.models::USER_DETAILS

  
    
  
  
    
      
        
      
      
        
          
          
          
          
        
        
        
        
        
      
      
        
      
      
        
      
      
        
      
      
        
      
    
  

This tool will even create a temporary OData V4 service for any existing table, view or Calculation View and launch a test Fiori Ui locally.

Project Structure and Documentation

Utils Documentation

For developers looking to understand or extend the internal utilities used by this CLI tool, comprehensive documentation is available in the [utils/README.md](utils/README.md) file. This documentation covers:

• Core Utilities: base module, connection management, database inspection, SQL injection protection
• CLI Integration: BTP, Cloud Foundry, and XSA CLI integration utilities
• Database Abstraction: Multi-database support (HANA, PostgreSQL, SQLite) with factory pattern
• Usage Examples: Practical examples for using the utility modules

The utils folder contains reusable modules that provide the foundation for all CLI commands, including database connectivity, terminal UI components, security utilities, and internationalization support.

HTTP Routes Documentation

The hana-cli tool includes a built-in web server that exposes all CLI functionality through RESTful HTTP endpoints. Detailed documentation for all HTTP routes is available in the [routes/README.md](routes/README.md) file. This document

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SAP-samples
• Source: SAP-samples/hana-developer-cli-tool-example
• License: Apache-2.0
• Homepage: https://sap-samples.github.io/hana-developer-cli-tool-example/

Install and usage instructions live in the source repository linked above.