Terminalna

Terminalna (tna) is a terminal-based AI CLI that converts natural language tasks into terminal commands, previews them, validates safety/dependencies, and executes them with user-controlled modes.

Features

• Interactive provider/model selection (Gemini, Claude, OpenAI, Mistral)
• API key prompt and persistence in ~/.terminalna/config.json (or .env)
• AI command generation with retry and command-only prompt shaping
• Command preview and execution modes:
  • Execute all
  • Execute first only
  • Step-by-step
• Safety layer for dangerous command detection
• Dependency checker + install suggestions (Windows/macOS/Linux)
• Windows admin guard for Chocolatey installs
• Command cache + prompt history
• Offline templates (optional fallback)
• Plugin-ready provider system (~/.terminalna/plugins/*.js)

Project Structure

terminalna/
├── bin/
│   └── tna.js
├── src/
│   ├── ai/
│   │   ├── claude.js
│   │   ├── gemini.js
│   │   ├── http.js
│   │   ├── mistral.js
│   │   ├── openai.js
│   │   └── providerRegistry.js
│   ├── cache/
│   │   └── cacheManager.js
│   ├── cli/
│   │   ├── modelSelector.js
│   │   └── prompt.js
│   ├── config/
│   │   ├── configManager.js
│   │   └── constants.js
│   ├── executor/
│   │   ├── commandRunner.js
│   │   └── validator.js
│   ├── history/
│   │   └── historyManager.js
│   ├── installer/
│   │   ├── dependencyChecker.js
│   │   └── installer.js
│   ├── plugins/
│   │   └── pluginLoader.js
│   ├── templates/
│   │   └── offlineTemplates.js
│   ├── utils/
│   │   └── display.js
│   └── index.js
├── tests/
│   └── smoke.test.js
├── .env
├── .gitignore
├── LICENSE
├── package.json
└── README.md

1) Create Project Folder (from scratch)

mkdir terminalna
Set-Location terminalna
npm init -y

2) Install Dependencies

npm install commander inquirer chalk ora execa dotenv

3) Local Run

npm start -- -m "Create a Flutter project and build an APK"

You can also run directly:

node ./bin/tna.js -m "Create a Flutter project and build an APK"

4) CLI Usage

tna -m "Create a Flutter project and build an APK"
tna --message "Create a Flutter project and build an APK"

Optional flags:

tna -m "Create flutter app" --provider gemini --model gemini-2.5-pro

tna -m "Create flutter app" --offline

tna -m "Create flutter app" --no-cache

5) API Key Handling

Priority:

1. Environment variables (.env)
2. Saved key in ~/.terminalna/config.json
3. Interactive prompt

Supported env keys:

• GEMINI_API_KEY
• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• MISTRAL_API_KEY

6) Safety and Validation

Before execution, Terminalna:

• scans generated commands for high-risk patterns (rm -rf /, mkfs, etc.)
• asks for explicit confirmation if dangerous commands exist
• detects missing tools from generated commands
• suggests install methods by OS:
  • Windows: Chocolatey
  • macOS: Homebrew
  • Linux: Snap/APT (configured per tool)

7) Execution Engine

src/executor/commandRunner.js supports:

• all commands
• first command only
• step-by-step mode

cd commands are handled internally so subsequent commands run in the correct directory.

8) Tests and Checks

npm test
npm run lint

9) Build a Global CLI Locally

npm link

tna -m "Create a Flutter project"

10) Publish to npm

A. Ensure unique package name

Check and, if needed, rename in package.json.

B. Login

npm login

C. Dry-run package contents

npm pack --dry-run

D. Publish

npm publish --access public

E. Install globally as users

npm install -g terminalna

tna -m "Create a Flutter project"

Plugin Provider Example (Optional)

Create ~/.terminalna/plugins/my-provider.js:

export default {
  id: "myprovider",
  name: "My Provider",
  models: ["my-model-1"],
  async generateCommands({ model, apiKey, message }) {
    return `echo Provider=${model}\necho ${message}`;
  }
};

Restart CLI and select the new provider from the menu.

Notes

• Requires Node.js 18+
• Uses global fetch (available in modern Node 18+)
• For Windows Chocolatey installs, run terminal as Administrator