@smart-dev-agency/smart-grow-secure-cli

CLI for managing and configuring variables and services for the Smart Grow App project.

Requirements

• Node.js 18.2.0 or newer.

Smart Grow Services

Smart Grow offers two service modes to fit your needs:

☁️ Smart Grow Vault

Secure Vault API for environment variables and credential files. The API URL can point to the managed Vault service or a licensed self-hosted Vault instance.

• Website: https://vault.smart-grow.app
• Features:
  • 🔐 OAuth Device Flow authentication
  • 🚀 Zero infrastructure management
  • 🔒 Post-quantum encryption
  • 📊 Usage analytics and monitoring
  • 👥 Team collaboration
  • 🌍 Global availability

Set SMARTGROW_VAULT_API_URL or pass --api-url when targeting a non-default Vault API URL.

🏢 Smart Grow OnPremise

self-hosted service with a different API and encryption contract.

• Website: https://smart-grow.app
• Features:
  • 🏠 Full control over your data
  • 🔧 Custom configurations
  • 🌐 Deploy on your own servers
  • 🔐 Your security policies
  • 📦 Air-gapped environments support
  • 🔑 API Token authentication for automation
  • 💾 Session-based authentication

Ideal for organizations with strict compliance requirements or those who prefer complete control over their infrastructure.

Installation

Global Installation

Install the package globally from npm:

npm install -g @smart-dev-agency/smart-grow-secure-cli

Then use it anywhere:

smart-grow

Using with npx (No Installation Required)

You can run the CLI directly without installing it globally using npx:

npx @smart-dev-agency/smart-grow-secure-cli

Benefits of using npx:

• ✅ Always uses the latest version
• ✅ No need to install globally
• ✅ Perfect for CI/CD pipelines
• ✅ No pollution of global node_modules

Examples with npx:

# Interactive mode
npx @smart-dev-agency/smart-grow-secure-cli

# Smart Grow Vault login
npx @smart-dev-agency/smart-grow-secure-cli cloud_login

# Smart Grow Vault download variables
npx @smart-dev-agency/smart-grow-secure-cli cloud_download

# Smart Grow Vault download a secure file
npx @smart-dev-agency/smart-grow-secure-cli cloud_download_file

# Smart Grow Vault sync variables for CI/CD
npx @smart-dev-agency/smart-grow-secure-cli cloud_sync \
  --api-url $SMARTGROW_VAULT_API_URL \
  --api-key $SMARTGROW_API_KEY \
  --org $SMARTGROW_ORG_ID \
  --app $SMARTGROW_APP_ID \
  --env $SMARTGROW_ENV_ID

# Smart Grow Vault sync secure file for CI/CD
npx @smart-dev-agency/smart-grow-secure-cli cloud_sync_file \
  --api-url $SMARTGROW_VAULT_API_URL \
  --api-key $SMARTGROW_API_KEY \
  --org $SMARTGROW_ORG_ID \
  --app $SMARTGROW_APP_ID \
  --env $SMARTGROW_ENV_ID \
  --file $SMARTGROW_FILE_ID

Usage

Interactive Mode (Recommended)

Simply run the CLI without any command to access the interactive menu:

smart-grow
# or with npx
npx @smart-dev-agency/smart-grow-secure-cli

This will show you a menu to choose between:

• ☁️ Smart Grow Vault - Vault API with secure authentication
• 🏢 OnPremise - Self-hosted service with own server

After selecting your deployment mode, you'll see the available commands for that mode.

Direct Command Mode

You can also run commands directly:

smart-grow <command>
# or with npx
npx @smart-dev-agency/smart-grow-secure-cli <command>

Available Commands

OnPremise Commands:

• login - Authenticate and create a CLI session (supports OAuth and Email/Password)
• logout - Sign out and remove saved session
• status - Show current session status
• download_variables - Download environment variables using saved session
• download_variables_with_token - Download variables using API Token (for CI/CD automation)
• download_files - Download encrypted secure files interactively
• download_files_with_token - Download encrypted secure files using API Token (for CI/CD automation)
• update_config_cli - Configures the CLI (name, server URL, and preferred scope)
• get_config_cli - Shows the current CLI configuration

Smart Grow Vault Commands:

• cloud_login - Authenticate with your Smart Grow Vault account
• cloud_download - Download environment variables interactively (with filename selection)
• cloud_download_file - Download an encrypted secure file interactively
• cloud_sync - Sync variables using API Key (designed for CI/CD automation)
• cloud_sync_file - Sync secure file using API Key (designed for CI/CD automation)
• cloud_status - Show current Smart Grow Vault session status and active server
• cloud_logout - Sign out from your Smart Grow Vault account
• vault_update_config - Configure the Smart Grow Vault API URL
• vault_get_config - Show the Smart Grow Vault configuration

OnPremise Authentication Workflow

Smart Grow OnPremise uses a two-step authentication process for better security and user experience:

1. Login (One-time Setup)

Authenticate once and save your session credentials:

smart-grow login
# or
npx @smart-dev-agency/smart-grow-secure-cli login

Supported authentication methods:

• 🔐 OAuth Providers: Apple, Azure, GitHub, GitLab, Google
• 📧 Email/Password: Traditional credentials
• 🔒 Two-Factor Authentication (2FA): Additional security layer when enabled

Your session is stored securely and remains valid for 30 days.

2. Download Variables (Multiple Uses)

Once authenticated, download variables as many times as needed without re-authenticating:

smart-grow download_variables
# or
npx @smart-dev-agency/smart-grow-secure-cli download_variables

Interactive steps:

1. Select your application
2. Choose the environment
3. Variables are downloaded and merged with existing .env file

All data is transmitted securely using hybrid encryption.

OnPremise Download Files (Interactive)

The download_files command provides an interactive experience for downloading encrypted secure files:

1. Authentication: Uses your saved session from login
2. Application Selection: Choose the application
3. Environment Selection: Select the environment
4. File Selection: Pick which file(s) to download
5. Decryption: Files are automatically decrypted and saved locally

smart-grow download_files
# or
npx @smart-dev-agency/smart-grow-secure-cli download_files

OnPremise Download Variables with API Token (CI/CD)

The download_variables_with_token command is designed for automated environments where interactive login isn't possible.

Key Features:

• 🔑 Uses API Token authentication (no session required)
• ⚙️ Multiple configuration methods for flexibility
• 🤖 Perfect for automated deployments and CI/CD pipelines
• 🔒 Secure transmission

Configuration Methods

The command supports three ways to provide configuration, with the following priority order:

CLI arguments > Environment variables > Config file

1. Environment Variables (⭐ RECOMMENDED for CI/CD)

This is the safest and most secure method for CI/CD pipelines. Store your secrets in your CI/CD platform's secret management system.

# Set variables (these should come from your CI/CD secrets)
export SMARTGROW_ONPREMISE_API_TOKEN=your_api_token
export SMARTGROW_ONPREMISE_APP_ID=your_app_id
export SMARTGROW_ONPREMISE_ENV_ID=your_env_id
export SMARTGROW_ONPREMISE_FORMAT=dotenv          # Optional: env or dotenv (default: dotenv)
export SMARTGROW_ONPREMISE_OUTPUT=smart-grow.env  # Optional: output file path

# Run the command - it will automatically pick up the environment variables
npx @smart-dev-agency/smart-grow-secure-cli download_variables_with_token

Benefits:

• ✅ No secrets in code or command history
• ✅ Native integration with CI/CD secret management
• ✅ Easy to rotate credentials
• ✅ Prevents accidental secret exposure

2. CLI Arguments

Use this method for testing or scripts:

npx @smart-dev-agency/smart-grow-secure-cli download_variables_with_token \
  --api-token YOUR_API_TOKEN \
  --app-id YOUR_APP_ID \
  --env-id YOUR_ENV_ID \
  --format dotenv \
  --output smart-grow.env

⚠️ Warning: CLI arguments may appear in shell history. Use environment variables in production.

3. Config File (Lowest Priority)

Create a smartgrow.onpremise.config.env file:

# Smart Grow OnPremise CLI Configuration

# API Token for authentication (required)
SMARTGROW_ONPREMISE_API_TOKEN=your_api_token_here

# Application ID (required)
SMARTGROW_ONPREMISE_APP_ID=your_app_id_here

# Environment ID (required)
SMARTGROW_ONPREMISE_ENV_ID=your_env_id_here

# Output format: env or dotenv (optional, default: dotenv)
SMARTGROW_ONPREMISE_FORMAT=dotenv

# Output file path (optional, default: smart-grow.env)
SMARTGROW_ONPREMISE_OUTPUT=smart-grow.env

Then run:

npx @smart-dev-agency/smart-grow-secure-cli download_variables_with_token \
  --config smartgrow.onpremise.config.env

⚠️ Important: Add smartgrow.onpremise.config.env to your .gitignore!

OnPremise Download Files with API Token (CI/CD)

The download_files_with_token command downloads encrypted secure files in automated environments without interactive login.

Key Features:

• 🔑 Uses API Token authentication (no session required)
• 📂 Downloads a specific file or all files for an environment
• ⚙️ Multiple configuration methods for flexibility
• 🤖 Designed for automated deployments and CI/CD pipelines
• 🔒 Files are decrypted automatically

Configuration Methods

The command supports three ways to provide configuration, with the following priority order:

CLI arguments > Environment variables > Config file

1. Environment Variables (⭐ RECOMMENDED for CI/CD)

export SMARTGROW_ONPREMISE_API_TOKEN=your_api_token
export SMARTGROW_ONPREMISE_APP_ID=your_app_id
export SMARTGROW_ONPREMISE_ENV_ID=your_env_id
export SMARTGROW_ONPREMISE_FILE_ID=your_file_id    # Optional: downloads all files if omitted
export SMARTGROW_ONPREMISE_FILE_OUTPUT=./secrets   # Optional: output directory (default: current dir)

npx @smart-dev-agency/smart-grow-secure-cli download_files_with_token

2. CLI Arguments

npx @smart-dev-agency/smart-grow-secure-cli download_files_with_token \
  --api-token YOUR_API_TOKEN \
  --app-id YOUR_APP_ID \
  --env-id YOUR_ENV_ID \
  --file-id YOUR_FILE_ID \
  --output ./secrets

3. Config File (Lowest Priority)

Create a smartgrow.onpremise.config.env file:

SMARTGROW_ONPREMISE_API_TOKEN=your_api_token_here
SMARTGROW_ONPREMISE_APP_ID=your_app_id_here
SMARTGROW_ONPREMISE_ENV_ID=your_env_id_here
SMARTGROW_ONPREMISE_FILE_ID=your_file_id_here      # Optional
SMARTGROW_ONPREMISE_FILE_OUTPUT=./secrets          # Optional

Then run:

npx @smart-dev-agency/smart-grow-secure-cli download_files_with_token \
  --config smartgrow.onpremise.config.env

⚠️ Important: Add smartgrow.onpremise.config.env to your .gitignore!

CI/CD Examples for OnPremise (Files)

GitHub Actions:

- name: Download secure files from Smart Grow OnPremise
  env:
    SMARTGROW_ONPREMISE_API_TOKEN: ${{ secrets.SMARTGROW_API_TOKEN }}
    SMARTGROW_ONPREMISE_APP_ID: ${{ secrets.SMARTGROW_APP_ID }}
    SMARTGROW_ONPREMISE_ENV_ID: ${{ secrets.SMARTGROW_ENV_ID }}
    SMARTGROW_ONPREMISE_FILE_OUTPUT: ./config
  run: npx @smart-dev-agency/smart-grow-secure-cli download_files_with_token

CI/CD Examples for OnPremise (Variables)

GitHub Actions:

name: Deploy with Smart Grow OnPremise

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Download environment variables
        env:
          SMARTGROW_ONPREMISE_API_TOKEN: ${{ secrets.SMARTGROW_API_TOKEN }}
          SMARTGROW_ONPREMISE_APP_ID: ${{ secrets.SMARTGROW_APP_ID }}
          SMARTGROW_ONPREMISE_ENV_ID: ${{ secrets.SMARTGROW_ENV_ID }}
        run: |
          npx @smart-dev-agency/smart-grow-secure-cli download_variables_with_token

      - name: Deploy
        run: |
          # Your deployment commands here
          npm run deploy

GitLab CI:

deploy:
  stage: deploy
  script:
    - npx @smart-dev-agency/smart-grow-secure-cli download_variables_with_token
    - npm run deploy
  variables:
    SMARTGROW_ONPREMISE_API_TOKEN: $SMARTGROW_API_TOKEN
    SMARTGROW_ONPREMISE_APP_ID: $SMARTGROW_APP_ID
    SMARTGROW_ONPREMISE_ENV_ID: $SMARTGROW_ENV_ID

Jenkins:

pipeline {
  agent any
  environment {
    SMARTGROW_ONPREMISE_API_TOKEN = credentials('smartgrow-api-token')
    SMARTGROW_ONPREMISE_APP_ID = credentials('smartgrow-app-id')
    SMARTGROW_ONPREMISE_ENV_ID = credentials('smartgrow-env-id')
  }
  stages {
    stage('Download Variables') {
      steps {
        sh 'npx @smart-dev-agency/smart-grow-secure-cli download_variables_with_token'
      }
    }
    stage('Deploy') {
      steps {
        sh 'npm run deploy'
      }
    }
  }
}

Cloud Download (Interactive)

The cloud_download and cloud_download_file commands provide an interactive experience:

1. Authentication: Uses your saved credentials from cloud_login
2. Organization Selection: Choose from your available organizations
3. Application Selection: Pick the application to download resources from
4. Environment Selection: Select the environment (development, staging, production, etc.)
5. Filename Selection: Choose the output filename

Example:

# For environment variables
smart-grow cloud_download

# For secure files
smart-grow cloud_download_file

All data is transmitted securely using post-quantum encryption.

Cloud Sync for CI/CD

The cloud_sync command is specifically designed for automated environments like CI/CD pipelines, GitHub Actions, GitLab CI, Jenkins, etc.

Key Features:

• 🔑 Uses API Key authentication (no interactive login required)
• ⚙️ Multiple configuration methods for flexibility
• 📦 Supports multiple output formats (JSON, ENV, dotenv)
• 🔒 Secure transmission with encryption
• 🎯 Perfect for automated deployments

Configuration Methods

The command supports three ways to provide configuration, with the following priority order:

Environment variables (RECOMMENDED for CI/CD) > CLI arguments > Config file

1. Environment Variables (⭐ RECOMMENDED for CI/CD)

This is the safest and most secure method for CI/CD pipelines. Store your secrets in your CI/CD platform's secret management system and expose them as environment variables.

# Set variables (these should come from your CI/CD secrets)
export SMARTGROW_API_KEY=your_api_key
export SMARTGROW_ORG_ID=your_org_id
export SMARTGROW_APP_ID=your_app_id
export SMARTGROW_ENV_ID=your_env_id
export SMARTGROW_FORMAT=dotenv              # Optional: json, env, or dotenv (default: dotenv)
export SMARTGROW_OUTPUT=smart-grow.env      # Optional: output file path

# Run the command - it will automatically pick up the environment variables
smart-grow cloud_sync

# With npx (recommended for CI/CD to always use latest version)
npx @smart-dev-agency/smart-grow-secure-cli cloud_sync

Benefits of using environment variables:

• ✅ No secrets in code or command history
• ✅ Native integration with CI/CD secret management
• ✅ Easy to rotate credentials without changing pipelines
• ✅ Works seamlessly across different CI/CD platforms
• ✅ Prevents accidental secret exposure in logs

2. CLI Arguments

Use this method for testing or when environment variables aren't available:

smart-grow cloud_sync \
  --api-key YOUR_API_KEY \
  --org YOUR_ORG_ID \
  --app YOUR_APP_ID \
  --env YOUR_ENV_ID \
  --format dotenv \
  --output smart-grow.env

# With npx
npx @smart-dev-agency/smart-grow-secure-cli cloud_sync \
  --api-key YOUR_API_KEY \
  --org YOUR_ORG_ID \
  --app YOUR_APP_ID \
  --env YOUR_ENV_ID

⚠️ Warning: CLI arguments may appear in shell history and process lists. Use environment variables in production.

3. Config File (Lowest Priority)

Create a smartgrow.config.env file (you can copy from smartgrow.config.env.example):

# Smart Grow CLI Configuration Example
# Copy this file and fill in your values

# API Key for authentication (required)
SMARTGROW_API_KEY=your_api_key_here

# Organization ID (required)
SMARTGROW_ORG_ID=your_org_id_here

# Application ID (required)
SMARTGROW_APP_ID=your_app_id_here

# Environment ID (required)
SMARTGROW_ENV_ID=your_env_id_here

# Output format: json, env, or dotenv (optional, default: dotenv)
SMARTGROW_FORMAT=dotenv

# Output file path (optional, default: smart-grow.env)
SMARTGROW_OUTPUT=smart-grow.env

Then run:

smart-grow cloud_sync --config smartgrow.config.env
# or
npx @smart-dev-agency/smart-grow-secure-cli cloud_sync --config smartgrow.config.env

⚠️ Important: Add smartgrow.config.env to your .gitignore to avoid committing secrets!

Output Options

Supported format scopes:

For cloud_sync (Variables):

• json - JSON object with key-value pairs
• env - Plain KEY=value format
• dotenv - .env format with proper escaping and comments (default)

Default output files:

• Variables (cloud_sync): smart-grow.env
• Secure files (cloud_sync_file): Uses the original uploaded filename

You can customize the outputs heavily with options like --output <filename> or via environment overrides based on the command needed.

CI/CD Examples

All examples below use environment variables (the recommended approach) to securely pass credentials from your CI/CD platform's secret management system.

GitHub Actions (Recommended):

name: Deploy with Smart Grow

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Download environment variables from Smart Grow
        env:
          # These secrets should be configured in GitHub Settings > Secrets
          SMARTGROW_API_KEY: ${{ secrets.SMARTGROW_API_KEY }}
          SMARTGROW_ORG_ID: ${{ secrets.SMARTGROW_ORG_ID }}
          SMARTGROW_APP_ID: ${{ secrets.SMARTGROW_APP_ID }}
          SMARTGROW_ENV_ID: ${{ secrets.SMARTGROW_ENV_ID }}
          SMARTGROW_FORMAT: dotenv
          SMARTGROW_OUTPUT: .env
        run: |
          # Uses npx to always get the latest version
          npx @smart-dev-agency/smart-grow-secure-cli cloud_sync

      - name: Load variables into environment
        run: |
          # Source the downloaded .env file
          export $(cat .env | xargs)
          # Your deployment commands here
          npm run build
          npm run deploy

GitLab CI (Recommended):

variables:
  # Configure these in GitLab Settings > CI/CD > Variables
  # Mark them as "Masked" and "Protected" for security
  SMARTGROW_FORMAT: "dotenv"
  SMARTGROW_OUTPUT: ".env"

download_and_deploy:
  stage: deploy
  script:
    # Variables SMARTGROW_API_KEY, SMARTGROW_ORG_ID, SMARTGROW_APP_ID,
    # and SMARTGROW_ENV_ID should be configured as CI/CD variables
    - npx @smart-dev-agency/smart-grow-secure-cli cloud_sync
    - export $(cat .env | xargs)
    - npm run build
    - npm run deploy
  only:
    - main

Jenkins (Recommended):

pipeline {
    agent any

    environment {
        // These should be configured in Jenkins Credentials
        SMARTGROW_API_KEY = credentials('smartgrow-api-key')
        SMARTGROW_ORG_ID = credentials('smartgrow-org-id')
        SMARTGROW_APP_ID = credentials('smartgrow-app-id')
        SMARTGROW_ENV_ID = credentials('smartgrow-env-id')
        SMARTGROW_FORMAT = 'dotenv'
        SMARTGROW_OUTPUT = '.env'
    }

    stages {
        stage('Download Variables') {
            steps {
                sh 'npx @smart-dev-agency/smart-grow-secure-cli cloud_sync'
            }
        }

        stage('Build and Deploy') {
            steps {
                sh '''
                    export $(cat .env | xargs)
                    npm run build
                    npm run deploy
                '''
            }
        }
    }
}

CircleCI:

version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout

      - run:
          name: Download Smart Grow Variables
          command: |
            # Configure these in CircleCI Project Settings > Environment Variables
            npx @smart-dev-agency/smart-grow-secure-cli cloud_sync

      - run:
          name: Deploy
          command: |
            export $(cat .env | xargs)
            npm run build
            npm run deploy

workflows:
  version: 2
  deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Azure Pipelines:

trigger:
  - main

pool:
  vmImage: "ubuntu-latest"

variables:
  # Configure these in Azure Pipelines Library as secret variables
  - group: SmartGrowSecrets
  - name: SMARTGROW_FORMAT
    value: "dotenv"
  - name: SMARTGROW_OUTPUT
    value: ".env"

steps:
  - script: |
      npx @smart-dev-agency/smart-grow-secure-cli cloud_sync
    displayName: "Download Smart Grow Variables"
    env:
      SMARTGROW_API_KEY: $(SMARTGROW_API_KEY)
      SMARTGROW_ORG_ID: $(SMARTGROW_ORG_ID)
      SMARTGROW_APP_ID: $(SMARTGROW_APP_ID)
      SMARTGROW_ENV_ID: $(SMARTGROW_ENV_ID)

  - script: |
      export $(cat .env | xargs)
      npm run build
      npm run deploy
    displayName: "Build and Deploy"

Bitbucket Pipelines:

pipelines:
  branches:
    main:
      - step:
          name: Deploy with Smart Grow
          script:
            # Configure these in Bitbucket Repository Settings > Pipelines > Repository variables
            # Mark as "Secured" for sensitive values
            - export SMARTGROW_FORMAT=dotenv
            - export SMARTGROW_OUTPUT=.env
            - npx @smart-dev-agency/smart-grow-secure-cli cloud_sync
            - export $(cat .env | xargs)
            - npm run build
            - npm run deploy

🔒 Security Best Practices for CI/CD:

1. Always use your CI/CD platform's secret management:

   • GitHub: Settings > Secrets and variables > Actions
   • GitLab: Settings > CI/CD > Variables (mark as Protected & Masked)
   • Jenkins: Manage Jenkins > Credentials
   • CircleCI: Project Settings > Environment Variables
   • Azure: Library > Variable groups (mark as secret)
   • Bitbucket: Repository settings > Pipelines > Repository variables (Secured)

2. Never hardcode credentials in your pipeline files

3. Use npx to always get the latest security patches:

   npx @smart-dev-agency/smart-grow-secure-cli cloud_sync

4. Rotate API keys regularly through the Smart Grow Vault dashboard

5. Use different API keys for different environments (dev, staging, production)

Usage Examples

# Interactive mode (recommended for first-time users)
smart-grow

# Smart Grow Vault: Login
smart-grow cloud_login

# Smart Grow Vault: Download variables interactively
smart-grow cloud_download

# Smart Grow Vault: Download a secure file interactively
smart-grow cloud_download_file

# Smart Grow Vault: Sync variables for CI/CD
smart-grow cloud_sync --api-key xxx --org xxx --app xxx --env xxx

# Smart Grow Vault: Sync secure file for CI/CD
smart-grow cloud_sync_file --api-key xxx --org xxx --app xxx --env xxx --file xxx

# Smart Grow Vault: Show session status and active server
smart-grow cloud_status

# Smart Grow Vault: Logout
smart-grow cloud_logout

# Smart Grow Vault: Configure API URL
smart-grow vault_update_config

# Smart Grow Vault: Show current API URL configuration
smart-grow vault_get_config

# OnPremise: Login
smart-grow login

# OnPremise: Show session status
smart-grow status

# OnPremise: Download variables
smart-grow download_variables

# OnPremise: Download secure files interactively
smart-grow download_files

# OnPremise: Download variables for CI/CD
smart-grow download_variables_with_token --api-token xxx --app-id xxx --env-id xxx

# OnPremise: Download secure files for CI/CD
smart-grow download_files_with_token --api-token xxx --app-id xxx --env-id xxx

# OnPremise: Configure CLI
smart-grow update_config_cli

# OnPremise: Show current configuration
smart-grow get_config_cli

# OnPremise: Logout
smart-grow logout

All commands work with npx:

# Just replace "smart-grow" with "npx @smart-dev-agency/smart-grow-secure-cli"
npx @smart-dev-agency/smart-grow-secure-cli cloud_download

Configuration Scopes

The OnPremise and Smart Grow Vault CLIs use separate repository-scoped configuration files so that every project can keep its own settings while still falling back to global defaults.

Smart Grow Vault

Smart Grow Vault stores only the Vault API URL. This is intentionally separate from the legacy OnPremise configuration because both services use different APIs and encryption contracts.

Configuration Resolution Order:

1. --api-url command option
2. Command config file values, for example SMARTGROW_VAULT_API_URL in smartgrow.config.env
3. SMARTGROW_VAULT_API_URL or SMARTGROW_API_URL environment variables
4. .smart-grow-vault-cli.json in the current working directory
5. Global Vault configuration stored by the CLI
6. Built-in default managed Vault API

Use these commands:

smart-grow vault_update_config
smart-grow vault_get_config
smart-grow cloud_status

cloud_status prints the active Vault server and the source being used.

Example .smart-grow-vault-cli.json:

{
  "api_url": "https://vault-api.my-server.com"
}

OnPremise

Configuration Resolution Order:

1. .smart-grow-cli.json in the current working directory (project-level)
2. Global configuration stored by the CLI (user-level)
3. Built-in defaults

Configuration Options:

When you run smart-grow update_config_cli, you can choose where to save your settings:

• Repository only – Creates/updates .smart-grow-cli.json in the current folder

  • ✅ Commit this file to share settings with your team
  • ✅ Each project can have different configurations

• Global only – Stores values in user-level configuration

  • ✅ Use across all projects
  • ✅ No project-specific files needed

• Both – Keeps both the repository and global configuration in sync

  • ✅ Flexibility to override globally when needed

Example .smart-grow-cli.json:

{
  "cli_name": "my-project",
  "api_url": "https://api.my-server.com",
  "file_name": ".env"
}

Note: Smart Grow Vault commands resolve the API URL from command options, CI/config-file values, environment variables, persistent Vault CLI config, or the default managed Vault API.

• Interactive selection (cloud_download)
• Direct parameters/env vars/config file (cloud_sync)

Security & Best Practices

🔐 Credentials Management

DO:

• ✅ Use environment variables in CI/CD (RECOMMENDED) - Pass credentials through your CI/CD platform's secret management
• ✅ Store API keys as encrypted secrets in your CI/CD platform:
  • GitHub: Settings > Secrets and variables > Actions
  • GitLab: Settings > CI/CD > Variables (Protected & Masked)
  • Jenkins: Credentials Store
  • CircleCI: Project Settings > Environment Variables
  • Azure Pipelines: Variable Groups (Secret)
• ✅ Add smartgrow.config.env and .env files to your .gitignore
• ✅ Use npx @smart-dev-agency/smart-grow-secure-cli in CI/CD to always get the latest security patches
• ✅ Rotate API keys regularly through the Smart Grow Vault dashboard
• ✅ Use different API keys for different environments (dev, staging, production)
• ✅ Review and minimize the scope of API key permissions

DON'T:

• ❌ Use CLI arguments to pass secrets in CI/CD (they appear in logs and process lists)
• ❌ Commit API keys, tokens, or smartgrow.config.env to your repository
• ❌ Share credentials via plain text (email, Slack, chat, etc.)
• ❌ Use production credentials in development environments
• ❌ Hard-code secrets in your application code or pipeline files
• ❌ Store secrets in version control, even in private repositories

🎯 CI/CD Configuration Priority

When using cloud_sync in CI/CD, prefer this secure configuration order:

1. Environment Variables ⭐ (RECOMMENDED - Most secure)
2. CLI Arguments (Use only for testing)
3. Config File (Not recommended for CI/CD)

Example of secure CI/CD setup:

# GitHub Actions
- name: Sync Smart Grow Variables
  env:
    SMARTGROW_API_KEY: ${{ secrets.SMARTGROW_API_KEY }}
    SMARTGROW_ORG_ID: ${{ secrets.SMARTGROW_ORG_ID }}
    SMARTGROW_APP_ID: ${{ secrets.SMARTGROW_APP_ID }}
    SMARTGROW_ENV_ID: ${{ secrets.SMARTGROW_ENV_ID }}
  run: npx @smart-dev-agency/smart-grow-secure-cli cloud_sync

🔒 Security notes you may need when using the CLI

Your data travels over encrypted connections and your saved session is protected on your machine — on a normal desktop there's nothing to configure. Two situations need action:

Running in CI / Docker / a server without a system keychain. There interactive login can't store a session unless you provide a storage key:

# Generate once and keep it in your CI secret store (do not commit it):
openssl rand -base64 32

# Provide it to the CLI:
export SMART_GROW_STORAGE_KEY="<base64-encoded 32-byte key>"

Token-based CI/CD commands (cloud_sync, download_variables_with_token, download_files_with_token) don't need this — they authenticate per run and don't store a session.

Connecting to a self-hosted server for the first time. The CLI shows the server's security fingerprint and asks you to confirm it once (compare it with the value your administrator gives you). After that it remembers the server. For CI, skip the prompt by pinning it explicitly:

export SMARTGROW_SERVER_KEY="<value your server prints at startup>"

If you ever see an "identity has changed" error, stop and check with your administrator before continuing — it can mean someone is intercepting the connection.

For details on how Smart Grow protects your data (encryption, key handling, etc.), see the Smart Grow Vault security documentation, not this guide — this README only covers using the CLI.

📝 Recommended .gitignore

Add these entries to your .gitignore:

# Smart Grow CLI - Downloaded variables
smart-grow.env
.env
.env.*

# Smart Grow CLI - Configuration with secrets (for cloud_sync)
smartgrow.config.env

# Smart Grow CLI - OnPremise configuration (commit if non-sensitive)
# .smart-grow-cli.json

# Smart Grow Vault CLI - URL configuration (commit only if the URL is intended to be shared)
# .smart-grow-vault-cli.json

Notes:

• ✅ Always ignore smartgrow.config.env (contains API keys)
• ✅ Always ignore smart-grow.env and .env* (downloaded variables)
• ⚠️ Optional: You may commit .smart-grow-cli.json for OnPremise if it only contains non-sensitive configuration like server URLs
• ⚠️ Optional: You may commit .smart-grow-vault-cli.json if the Vault API URL is meant to be shared by the repository
• 📋 The file smartgrow.config.env.example can be committed as a template (without real values)

Troubleshooting

Command not found: smart-grow

If you installed globally and the command is not found:

# Check if it's installed
npm list -g @smart-dev-agency/smart-grow-secure-cli

# Reinstall
npm install -g @smart-dev-agency/smart-grow-secure-cli

# Or use npx (no installation needed)
npx @smart-dev-agency/smart-grow-secure-cli

Authentication errors in CI/CD

Make sure your environment variables are properly set:

# Test locally first
export SMARTGROW_API_KEY="your_key"
export SMARTGROW_ORG_ID="org_xxx"
export SMARTGROW_APP_ID="app_xxx"
export SMARTGROW_ENV_ID="env_xxx"

npx @smart-dev-agency/smart-grow-secure-cli cloud_sync

Permission denied errors

If you get permission errors during global installation:

# Option 1: Use npx (recommended)
npx @smart-dev-agency/smart-grow-secure-cli

# Option 2: Fix npm permissions
# https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

License

PROPRIETARY AND CONFIDENTIAL

Copyright © 2025 Smart Dev Agency S.A.S. All rights reserved.

This software is provided under a proprietary license. Use of this software is permitted only as explicitly authorized. Any unauthorized copying, distribution, modification, reverse engineering, decompilation, or extraction is strictly prohibited.

See the LICENSE file for complete terms and conditions.

For licensing inquiries or commercial use, contact: [email protected]

Support

For issues, questions, or feature requests:

Smart Grow Vault:

• 🌐 Website: https://vault.smart-grow.app
• 📧 Email: [email protected]
• 📚 Documentation: https://vault.smart-grow.app/docs

Smart Grow OnPremise:

• 🌐 Website: https://smart-grow.app
• 📧 Email: [email protected]
• 📚 Documentation: https://docs.smart-grow.app