All AI in one agentic coding tool. Ailin¹ Developer Tool - CLI understands your codebase to accelerate your workflow and helps you code, build, refactor, and debug faster — all through natural-language commands.
npm install @ailinone/dev-toolAilin API backend and mirrors its authentication, RBAC, telemetry, and observability stack.
>= 18.0.0
>= 8.0.0
tree-sitter binding is not available for the current platform/Node.js ABI the installer will compile one locally. Windows users on Node.js 22+ must have the Visual Studio Build Tools 2022 workload “Desktop development with C++” + the latest Windows SDK installed. On macOS, install the Xcode Command Line Tools (xcode-select --install). See docs/PREBUILDS.md for the prebuild publishing pipeline.
api/README.md)
powershell
Using npm
npm install -g @ailinone/dev-tool
Using pnpm (if scripts are blocked, see troubleshooting below)
pnpm add -g @ailinone/dev-tool
`
Note for pnpm users: If you see warnings about ignored build scripts, the CLI will still work but keytar (secure storage) may not be available. To fix this:
1. Option 1: Allow scripts for this package:
`powershell
pnpm config set enable-pre-post-scripts true
pnpm add -g @ailinone/dev-tool
`
2. Option 2: Use the cross-platform helper script:
`bash
# After installation, run:
npx @ailinone/dev-tool fix-keytar
# or if CLI is already in PATH:
ailin fix-keytar
`
3. Option 3: Manual rebuild (if helper script doesn't work):
`bash
# Find keytar location
npm list -g keytar
# Navigate to the shown path and run:
npm rebuild --build-from-source
`
The CLI will work even without keytar, using encrypted file storage as fallback.
$3
`bash
Clone the repository
git clone https://github.com/ailinone/dev-tool.git
cd dev-tool/cli
Install dependencies
pnpm install
pnpm build
`
During development you can run:
`powershell
pnpm dev # starts the CLI in watch mode
pnpm dev:mock # runs the CLI against the local mock server
pnpm mock:server # mock API only
`
The published package exposes the ailin binary. For local mono-repo usage you can execute with pnpm exec tsx src/index.ts.
---
First-Time Setup
1. Run the setup wizard
`powershell
ailin setup
`
The wizard collects API credentials, organization metadata, preferred models, and UI defaults. Secrets are stored through the secure storage layer (keytar on supported platforms).
2. Use environment variables (optional)
- AILIN_API_URL, AILIN_API_KEY, AILIN_ORG_ID
- AILIN_USER_EMAIL when using email-code login
- AILIN_DEFAULT_MODEL, AILIN_FALLBACK_MODEL
- AILIN_TUI_MODE for the preferred TUI mode
3. Check validation
`powershell
ailin config list
ailin config get api
`
The CLI validates configuration on every run and explains missing requirements (API key, organization ID, etc.).
Configuration is persisted to %USERPROFILE%\.ailin\config.json. Sensitive values (api.key, api.authToken, api.refreshToken) are persisted via secure storage and omitted from disk.
---
Key Features
- Interactive chat & one-shot prompts – Default entry point (ailin or ailin chat) launches an intelligent TUI that renders diffs, code blocks, and tool usage with streaming responses.
- Advanced/Basic TUI modes – --tui-mode advanced (default) offers Ink-based rendering with tool call visualization; --tui-mode basic falls back to Inquirer prompts for maximum compatibility.
- Workflow automation – ailin watch, ailin tdd, alias macros, and advanced watch comments (@ailin? / @ailin!) enable continuous AI-driven operations.
- Deep code understanding – Tree-sitter powered parsing, AST analysis, symbol extraction, dependency graphs, and impact analysis exposed through the @ailinone/cli/codebase module.
- Session management – Persist, inspect, export, and delete conversation sessions from the terminal.
- Checkpointing – Capture/restore file + conversation state snapshots to experiment safely.
- Plugin system – Load TypeScript/JavaScript plugins that register tools, subscribe to hooks, or add custom CLI commands.
- Enterprise controls – Inspect quotas, billing details, feature flags, users, and teams directly from the CLI with RBAC-aware APIs.
- Telemetry & metrics – Emit and inspect OpenTelemetry traces/logs/metrics; view local performance metrics via ailin metrics.
- Localization – Built-in translations for multiple locales (English, Spanish, Portuguese, French, German, Italian, Dutch, Japanese, Korean, Chinese, Arabic, Hebrew, Russian).
---
Usage Guide
$3
- ailin – Launch advanced TUI chat or execute a one-shot prompt when arguments are provided.
`powershell
ailin # interactive chat
ailin "Refactor the payment service" # one-shot prompt
ailin -m anthropic-claude-3-5-sonnet "Summarize src/index.ts"
ailin --diff "Create a new CLI command" # dry-run mode
ailin --clipboard "Explain the last commit" # copy last code block
`
- ailin chat --tui-mode basic – Force the lightweight interface (useful in constrained terminals or CI).
$3
- ailin setup – Re-run the onboarding wizard.
- ailin config list – Dump merged configuration.
- ailin config get – Retrieve nested config values (e.g., ailin config get models).
- ailin config set – Persist overrides (value accepts JSON strings).
$3
- ailin sessions --list – Show stored sessions, highlight the active conversation.
- ailin sessions --show – Display metadata, message count, timestamps.
- ailin sessions --delete / --clear – Clean up sessions.
- ailin sessions --export – Export JSON for audits or handovers.
$3
- ailin watch – Watch files, run shell commands, or route changes through the AI agent.
- --pattern / --ignore accept glob patterns.
- --command executes on change.
- --ai transforms change events into AI prompts.
- --advanced enables smart comment triggers. Comments such as // @ailin? Summarize this file or // @ailin! add tests can auto-trigger prompts; disable execution with --no-auto-execute.
- ailin tdd – Continuous test-driven loop.
- Watches source files, runs the provided test command, and optionally lets the agent auto-fix failing tests.
- --test-command defines the script (default npm test), --no-auto-fix disables automated remediation.
- ailin alias – Manage prompt macros.
- ailin alias set hotfix "Write a hotfix plan for {{module}}" -d "Incident runbook"
- ailin alias run hotfix -v module=payment-service
- Supports usage statistics and templated variables.
- ailin checkpoint – Snapshot and restore project state.
- create, list, show, restore [--dry-run], delete
- Stores file hashes, conversation metadata, and tool invocation context.
$3
- ailin plugins list – Enumerate detected plugins (active/inactive).
- ailin plugins enable ./plugins/my-plugin.js
- ailin plugins disable my-plugin
Plugins can register new CLI commands, tools, or hook listeners. See docs/PLUGIN_SYSTEM.md and examples/example-plugin.ts for complete walkthroughs.
$3
- ailin models list / ailin models info – Inspect synchronized model catalog (provider, context window, pricing, capabilities).
- ailin theme list | set – Switch or store custom themes for the TUI.
$3
- ailin debug-last-error – Print the most recent command failure and request an AI explanation.
- ailin metrics – View local performance metrics; supports filtering, exporting (--export metrics.json), Prometheus format, operation stats, and clearing.
- ailin update – Check the npm registry for new CLI versions.
- ailin version – Display current CLI version banner.
$3
All enterprise commands require appropriate roles (as defined by the backend RBAC policies).
- ailin enterprise users – Launch interactive user management (IdP-backed permission system).
- ailin enterprise teams – Manage teams and organizational structure.
Quotas
`powershell
ailin enterprise quotas --list
ailin enterprise quotas --usage
ailin enterprise quotas --set @configs/quota.json
ailin enterprise quotas --check @payloads/operation.json
ailin enterprise quotas --reset --period month
`
Billing & invoicing
`powershell
ailin enterprise billing --config-get
ailin enterprise billing --plans --plans-refresh
ailin enterprise billing --invoices
ailin enterprise billing --invoice-create @invoice.json
ailin enterprise billing --payment-methods
ailin enterprise billing --payment-method-attach pm_123
`
Audit logging
`powershell
Summary with counts per type/result
ailin enterprise audit --summary
Tail denied events and export to JSON
ailin enterprise audit --tail 20 --result denied --export logs/audit-denied.json
Filter by user, resource and time window
ailin enterprise audit --type permission_granted --user svc-ci --start "2025-01-01T00:00:00Z"
`
Configuration example (security.audit in config.json):
`json
"security": {
"sandboxTimeout": 30000,
"sandboxMaxMemory": 268435456,
"audit": {
"logDirectory": "C:/ailin/audit-logs",
"maxFileSize": 10485760,
"maxFiles": 30,
"enableConsole": false
}
}
`
Feature flags
`powershell
ailin enterprise features --list
ailin enterprise features --enable codegen_v2
ailin enterprise features --disable beta_ui
`
$3
The CLI ships with an OpenTelemetry SDK (core/telemetry) that can export traces, metrics, and logs via OTLP HTTP/GRPC. Configure using:
- AILIN_OTEL_ENABLED, AILIN_OTEL_EXPORTER, etc. (see docs/PERFORMANCE_CONFIGURATION.md)
- Rate limiter namespaces ensure telemetry floods are contained.
- Audit events emit AUDIT_EVENTS_* metrics (total, denied, write failures, duration) for SOC monitoring.
---
Code Understanding APIs
The package exports analysis utilities for integrating Ailin’s code intelligence into other tooling:
- CodebaseAnalyzer – Analyze files, a whole repository, compute statistics, detect circular dependencies, derive impacted files.
- CodeParser – Tree-sitter based parsing with language autodetection.
- ASTAnalyzer – Traverse ASTs to extract functions, classes, imports/exports.
- SymbolExtractor – Index and query symbols across the codebase.
- DependencyGraphBuilder – Build graph structures, export DOT/JSON.
Example (TypeScript):
`typescript
import { CodebaseAnalyzer } from '@ailinone/cli/codebase';
const analyzer = new CodebaseAnalyzer();
await analyzer.analyzeCodebase('./src', {
include: ['/.ts', '/.tsx'],
exclude: ['/node_modules/', '/.git/'],
});
const functions = analyzer.findSymbolsByType('function');
console.log(Functions found: ${functions.length});
`
Supported languages include TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, with optional grammars for many others via optional dependencies.
---
Configuration Reference
Configuration keys follow the structure defined in src/config/config-manager.ts. Highlights:
- api – Backend URL, credentials, organization ID, login mode, queue timeouts, negotiated feature flags.
- models – Default/fallback IDs, per-capability preferences, usage limits, temperature.
- tools.approvals – Approval policy (auto, ask, deny) for file operations, shell commands, git commands.
- codebase – Indexing behavior, ignore patterns, size limits, project identifiers.
- security – Sandbox limits, allowed/blocked executables, command rate limits.
- plugins – Enabled plugin entries and directory.
- permissions – RBAC defaults and custom role bindings.
- ui – TUI mode, colors, theme overrides.
- performance.rateLimiter – Global and namespace throttling values.
Use ailin config set permissions.defaultRole "reviewer" to adjust defaults or modify %USERPROFILE%\.ailin\config.json directly.
---
Testing
`powershell
pnpm test # unit + integration
pnpm test:watch # watch mode
pnpm test:coverage # coverage report
pnpm test:e2e # CLI end-to-end suite
pnpm validation-tests # see validation-tests/ README for advanced scenarios
`
Mocked runs can use the bundled server (pnpm dev:mock). Integration suites expect access to the real API unless otherwise configured.
---
Advanced Documentation
- docs/CODE_UNDERSTANDING.md – In-depth explanation of the parser and symbol engine.
- docs/TUI_MODE_GUIDE.md – UI customization and fallbacks.
- docs/PERFORMANCE_CONFIGURATION.md – Fine-tune rate limiting + telemetry exporters.
- docs/CLI_ARCHITECTURE_AUDIT.md – Enterprise architecture backlog & status. See “Status Update (Wave 1)” for current wins.
- docs/AUDIT_LOGGING.md (coming soon) – Deep dive into audit log configuration, log rotation, and SIEM ingestion.
- docs/LANGUAGE_STRATEGY_GUIDE.md – Multi-language prompts and translation strategy.
- docs/PLUGIN_SYSTEM.md – Writing, packaging, and publishing plugins.
- docs/PREBUILDS.md – Generating and shipping native bindings.
- docs/BUNDLING.md – Single-file distribution strategy and bundling pipeline.
- docs/TUI_MODE_GUIDE.md, docs/DESIGN_SYSTEM.md – Terminal UI components and theming.
- examples/ – Sample prompts, plugin templates, TUI demos.
---
Troubleshooting
$3
Problem: "Keytar not available" warning after installation.
Why this happens:
- pnpm blocks build scripts by default for security
- Native modules (keytar) need to be compiled during installation
- Visual Studio Build Tools may not be detected
Solutions:
1. Allow pnpm scripts (recommended):
`powershell
pnpm config set enable-pre-post-scripts true
pnpm add -g @ailinone/dev-tool --force
`
2. Manual rebuild after installation:
`powershell
# Find keytar location
$keytarPath = Get-ChildItem "$env:LOCALAPPDATA\pnpm\global\5\.pnpm\keytar@*\node_modules\keytar" -Directory | Select-Object -First 1
cd $keytarPath.FullName
npm rebuild --build-from-source
`
3. Use helper script (if installed from source):
`powershell
cd C:\GitHub\ailin.one\ailin-dev\cli
.\scripts\fix-keytar.ps1
`
4. Install Visual Studio Build Tools (if missing):
- Download: https://visualstudio.microsoft.com/visual-cpp-build-tools/
- Select "Desktop development with C++" workload
- Restart terminal after installation
Note: The CLI works perfectly fine without keytar. It will use encrypted file storage as fallback. Keytar is only needed for system keychain integration (optional feature).
$3
- Authentication required – Ensure AILIN_API_KEY or email-based login is configured. ailin setup can refresh tokens.
- Version mismatch – The CLI negotiates minimum/maximum compatible versions with the server. Upgrade if prompted (ailin update).
- Plugin errors – The CLI logs warnings during startup. Use ailin plugins list --all to investigate inactive plugins.
- Advanced TUI issues – Set AILIN_TUI_MODE=basic or run ailin chat --tui-mode basic.
- Sandbox denials – Adjust security.sandboxAllowedExecutables via config/environment.
- Rate limits – Modify performance.rateLimiter or specific namespace limits in config.
For deeper operational guidance consult api/docs/OPERATIONS_RUNBOOK.md and the observability/disaster recovery guides in the API project.
---
License
Distributed under the ISC license. See LICENSE` for details.