@adverant-nexus/cli 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +495 -35
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,75 +1,535 @@
1
- # @adverant/nexus-cli
1
+ <div align="center">
2
+ <img src="https://raw.githubusercontent.com/adverant/Adverant-Nexus-CLI/main/docs/images/adverant-logo-final.svg" alt="Adverant" width="280"/>
2
3
 
3
- > Command-line interface for the Adverant-Nexus platform
4
+ # Nexus CLI
4
5
 
5
- [![Version](https://img.shields.io/npm/v/@adverant/nexus-cli.svg)](https://www.npmjs.com/package/@adverant/nexus-cli)
6
- [![License](https://img.shields.io/npm/l/@adverant/nexus-cli.svg)](https://github.com/adverant/nexus-cli/blob/main/LICENSE)
6
+ **Enterprise-Grade CLI for AI-Powered Development**
7
7
 
8
- ## Installation
8
+ [![npm version](https://img.shields.io/npm/v/@adverant-nexus/cli.svg)](https://www.npmjs.com/package/@adverant-nexus/cli)
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
11
+ [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-green.svg)](https://nodejs.org/)
12
+
13
+ **Version:** 3.0.0 | **Last Updated:** December 2024
14
+
15
+ [Why Nexus?](#why-nexus-cli) &#8226; [Features](#-features) &#8226; [Quick Start](#-quick-start) &#8226; [Commands](#-command-reference) &#8226; [Architecture](#-architecture) &#8226; [Contributing](#-contributing)
16
+
17
+ </div>
18
+
19
+ ---
20
+
21
+ ## Why Nexus CLI?
22
+
23
+ **Most AI CLIs give you a chatbot. Nexus gives you a command center.**
24
+
25
+ Developers often juggle multiple tools, copy context between terminals, and lose track of what each system knows. Nexus CLI was built to unify your AI-powered workflow into a single, coherent interface.
26
+
27
+ ### Key Capabilities
28
+
29
+ | Capability | Description |
30
+ |------------|-------------|
31
+ | **Auto-Discovery** | Automatically detects and integrates 32+ microservices |
32
+ | **MCP Integration** | 70+ Model Context Protocol tools exposed as commands |
33
+ | **Multi-Agent Orchestration** | Run 10+ concurrent AI agents for complex tasks |
34
+ | **ReAct Agent Mode** | Autonomous task execution with up to 20 iterations |
35
+ | **Interactive REPL** | Full-featured shell with history and tab completion |
36
+ | **Plugin SDK** | Complete extensibility for custom integrations |
37
+ | **Workflow Automation** | YAML-based workflows with visual builder |
38
+ | **Real-time Monitoring** | Dashboard with alerts and performance metrics |
39
+ | **Cost Tracking** | Built-in usage analytics per operation |
40
+ | **Session Management** | Save, resume, and checkpoint your work |
41
+ | **Collaboration** | Multi-user sessions for team workflows |
42
+ | **Streaming** | WebSocket and SSE support for real-time updates |
43
+
44
+ ---
45
+
46
+ ## The Problem We Solve
47
+
48
+ ```
49
+ BEFORE: Fragmented Tooling
50
+
51
+ Your Terminal --> Tool A Custom Scripts Tool B
52
+ | | |
53
+ v v v
54
+ Context Lost | No Integration | Limited Features
55
+
56
+ AFTER: Unified Command Center
57
+
58
+ Your Terminal --> NEXUS CLI
59
+ - 32+ Services
60
+ - 70+ MCP Tools
61
+ - 10+ Agents
62
+ - Full Context
63
+ |
64
+ +----------------+----------------+
65
+ v v v
66
+ GraphRAG MageAgent Gateway
67
+ ```
68
+
69
+ ---
70
+
71
+ ## Features
72
+
73
+ ### Auto-Discovery & Integration
74
+
75
+ Stop configuring. Start building.
76
+
77
+ - **Automatic service detection** from Docker Compose, Kubernetes, and OpenAPI specs
78
+ - **70+ MCP tools** exposed through Model Context Protocol integration
79
+ - **32+ microservices** accessible through a single CLI
80
+ - **500+ API endpoints** auto-generated as commands
81
+ - **Plugin auto-loading** from `~/.nexus/plugins/`
9
82
 
10
83
  ```bash
11
- # Global installation
12
- npm install -g @adverant/nexus-cli
84
+ # Nexus discovers your entire stack automatically
85
+ nexus services list
86
+ # Output: 32 services discovered, 47 healthy, 0 degraded
13
87
 
14
- # Or use npx
15
- npx @adverant/nexus-cli --version
88
+ nexus mcp tools
89
+ # Output: 70 tools available across 12 providers
16
90
  ```
17
91
 
18
- ## Usage
92
+ ### Intelligent Automation
93
+
94
+ Your AI that actually gets things done.
95
+
96
+ - **Natural language commands**: Just describe what you want
97
+ - **ReAct agent mode**: 20 autonomous iterations with reasoning
98
+ - **Multi-agent orchestration**: Up to 10 concurrent specialized agents
99
+ - **Context-aware execution**: Remembers your stack, preferences, and patterns
100
+ - **Workflow templates**: YAML-defined automation pipelines
19
101
 
20
102
  ```bash
21
- # Check version
22
- nexus --version
103
+ # Natural language - Nexus understands intent
104
+ nexus ask "Deploy the latest GraphRAG changes to staging"
23
105
 
24
- # List all services
25
- nexus services list
106
+ # ReAct agent - autonomous problem solving
107
+ nexus agent task "Analyze the codebase and suggest performance improvements" --iterations 20
108
+
109
+ # Multi-agent - parallel specialized work
110
+ nexus agent orchestrate --agents "code-review,security-scan,test-coverage"
111
+ ```
112
+
113
+ ### Extensible Architecture
114
+
115
+ Build on top of Nexus, don't work around it.
116
+
117
+ - **Plugin SDK** with full TypeScript support
118
+ - **Hot-reloadable** plugins without restart
119
+ - **Permission-based sandbox** for security
120
+ - **Custom commands** via workspace configuration
121
+ - **MCP protocol** support for tool integration
122
+
123
+ ```typescript
124
+ // Create a plugin in minutes
125
+ import { NexusPlugin, command } from '@adverant-nexus/sdk';
126
+
127
+ export default class MyPlugin extends NexusPlugin {
128
+ @command('greet', 'Say hello')
129
+ async greet(name: string) {
130
+ return `Hello, ${name}! Welcome to Nexus.`;
131
+ }
132
+ }
133
+ ```
134
+
135
+ ### Rich Developer Experience
136
+
137
+ Built by developers, for developers who demand excellence.
26
138
 
27
- # Start interactive REPL
139
+ - **Interactive REPL** with full history and tab completion
140
+ - **Session checkpointing**: Save work, switch contexts, resume later
141
+ - **Multiple output formats**: JSON, YAML, Table, Streaming
142
+ - **Git integration**: Status, diff, commit from Nexus
143
+ - **Real-time streaming**: Watch operations as they happen
144
+
145
+ ```bash
146
+ # Interactive mode - your AI command center
28
147
  nexus repl
29
148
 
30
- # Get help
149
+ nexus> services health --all
150
+ nexus> agent start research --topic "GraphRAG optimization"
151
+ nexus> session save "morning-work"
152
+ nexus> exit
153
+
154
+ # Resume exactly where you left off
155
+ nexus session load "morning-work"
156
+ ```
157
+
158
+ ### Monitoring & Analytics
159
+
160
+ Know everything. Miss nothing.
161
+
162
+ - **Service health dashboard** with live updates
163
+ - **Custom alert conditions** with webhooks and notifications
164
+ - **Performance metrics** per operation
165
+ - **Cost tracking** for API operations
166
+ - **Time-series analytics** for optimization
167
+
168
+ ```bash
169
+ # Real-time health monitoring
170
+ nexus monitor --dashboard
171
+
172
+ # Cost analysis
173
+ nexus analytics costs --period 30d
174
+ # Output: Total: $47.82 | GraphRAG: $23.41 | MageAgent: $18.90 | Other: $5.51
175
+
176
+ # Performance insights
177
+ nexus analytics performance --service graphrag
178
+ ```
179
+
180
+ ---
181
+
182
+ ## Quick Start
183
+
184
+ ### Installation
185
+
186
+ ```bash
187
+ # npm (recommended)
188
+ npm install -g @adverant-nexus/cli
189
+
190
+ # yarn
191
+ yarn global add @adverant-nexus/cli
192
+
193
+ # pnpm
194
+ pnpm add -g @adverant-nexus/cli
195
+ ```
196
+
197
+ ### First Run
198
+
199
+ ```bash
200
+ # 1. Configure your API endpoint
201
+ nexus config set services.apiUrl https://your-nexus-api.com
202
+
203
+ # 2. Authenticate
204
+ nexus auth login
205
+ # Opens browser for OAuth, or use API key:
206
+ nexus auth login --api-key YOUR_API_KEY
207
+
208
+ # 3. Verify connection
209
+ nexus services health
210
+
211
+ # 4. Explore what's available
31
212
  nexus --help
213
+ nexus services list
214
+ nexus mcp tools
32
215
  ```
33
216
 
34
- ## Features
217
+ ### Your First Commands
218
+
219
+ ```bash
220
+ # Ask a natural language question
221
+ nexus ask "What services are currently running?"
222
+
223
+ # Check all service health
224
+ nexus services health --all
225
+
226
+ # Start an interactive session
227
+ nexus repl
228
+
229
+ # Run an autonomous agent task
230
+ nexus agent task "Analyze authentication patterns in the codebase"
231
+ ```
232
+
233
+ ---
35
234
 
36
- - 🚀 Auto-discovery of services from docker-compose and OpenAPI
37
- - 🤖 Autonomous agent mode with ReAct framework
38
- - 🔌 Extensible plugin system with SDK
39
- - 📊 Multiple output formats (text, JSON, YAML, table)
40
- - 🎨 Interactive REPL with command history
41
- - 🔍 Real-time service monitoring and health checks
42
- - 🔧 Workspace and session management
235
+ ## Command Reference
236
+
237
+ ### Core Commands
238
+
239
+ | Command | Description |
240
+ |---------|-------------|
241
+ | `nexus auth login` | Authenticate with Nexus API |
242
+ | `nexus auth logout` | Clear stored credentials |
243
+ | `nexus auth whoami` | Show current user info |
244
+ | `nexus config set <key> <value>` | Update configuration |
245
+ | `nexus config get <key>` | Get configuration value |
246
+
247
+ ### Service Commands
248
+
249
+ | Command | Description |
250
+ |---------|-------------|
251
+ | `nexus services list` | List all discovered services |
252
+ | `nexus services health [--all]` | Check service health |
253
+ | `nexus services info <service>` | Get detailed service info |
254
+ | `nexus services logs <service>` | Stream service logs |
255
+ | `nexus services restart <service>` | Restart a service |
256
+
257
+ ### Agent Commands
258
+
259
+ | Command | Description |
260
+ |---------|-------------|
261
+ | `nexus agent task <description>` | Run autonomous agent task |
262
+ | `nexus agent orchestrate` | Multi-agent orchestration |
263
+ | `nexus agent status <id>` | Check agent task status |
264
+ | `nexus agent list` | List running agents |
265
+ | `nexus agent stop <id>` | Stop running agent |
266
+
267
+ ### MCP Commands
268
+
269
+ | Command | Description |
270
+ |---------|-------------|
271
+ | `nexus mcp tools` | List available MCP tools |
272
+ | `nexus mcp run <tool> [args]` | Execute an MCP tool |
273
+ | `nexus mcp servers` | List MCP servers |
274
+ | `nexus mcp status` | MCP connection status |
275
+
276
+ ### Session Commands
277
+
278
+ | Command | Description |
279
+ |---------|-------------|
280
+ | `nexus session save <name>` | Save current session |
281
+ | `nexus session load <name>` | Load saved session |
282
+ | `nexus session list` | List all saved sessions |
283
+ | `nexus session export` | Export session to file |
284
+
285
+ ### Workflow Commands
286
+
287
+ | Command | Description |
288
+ |---------|-------------|
289
+ | `nexus workflow run <file>` | Execute workflow from YAML |
290
+ | `nexus workflow create` | Interactive workflow builder |
291
+ | `nexus workflow list` | List saved workflows |
292
+ | `nexus workflow status <id>` | Check workflow status |
293
+
294
+ ### Analytics Commands
295
+
296
+ | Command | Description |
297
+ |---------|-------------|
298
+ | `nexus analytics costs` | View cost breakdown |
299
+ | `nexus analytics usage` | View usage statistics |
300
+ | `nexus analytics performance` | Performance metrics |
301
+
302
+ ---
303
+
304
+ ## Architecture
305
+
306
+ ```
307
+ +-----------------------------------------------------------------------------+
308
+ | NEXUS CLI |
309
+ +-----------------------------------------------------------------------------+
310
+ | |
311
+ | +------------------+ +------------------+ +-------------------------+ |
312
+ | | Commands | | REPL | | Plugin System | |
313
+ | | (60+ cmds) | | (Interactive) | | (SDK + Hooks) | |
314
+ | +--------+---------+ +--------+---------+ +------------+------------+ |
315
+ | | | | |
316
+ | +---------------------+-------------------------+ |
317
+ | | |
318
+ | +------------v------------+ |
319
+ | | Command Router | |
320
+ | | (Discovery + Routing) | |
321
+ | +------------+------------+ |
322
+ | | |
323
+ | +---------------------+---------------------+ |
324
+ | | | | |
325
+ | +------v------+ +------v------+ +------v------+ |
326
+ | | HTTP Client | | WebSocket | | MCP | |
327
+ | | (REST API) | | (Streaming) | | (Tools) | |
328
+ | +------+------+ +------+------+ +------+------+ |
329
+ | | | | |
330
+ +------------+---------------------+---------------------+--------------------+
331
+ | | |
332
+ v v v
333
+ +-----------------------------------------------------------------------------+
334
+ | NEXUS PLATFORM SERVICES |
335
+ +-----------------------------------------------------------------------------+
336
+ | |
337
+ | +-------------+ +-------------+ +-------------+ +-----------------+ |
338
+ | | GraphRAG | | MageAgent | | Gateway | | 32+ More... | |
339
+ | | Memory | | Agents | | Routing | | Services | |
340
+ | +-------------+ +-------------+ +-------------+ +-----------------+ |
341
+ | |
342
+ +-----------------------------------------------------------------------------+
343
+ ```
344
+
345
+ ---
43
346
 
44
347
  ## Configuration
45
348
 
46
- Global configuration: `~/.nexus/config.toml`
47
- Workspace configuration: `.nexus.toml`
349
+ ### Environment Variables
350
+
351
+ ```bash
352
+ # Required
353
+ NEXUS_API_URL=https://your-nexus-api.com
354
+
355
+ # Authentication (choose one)
356
+ NEXUS_API_KEY=your_api_key_here
357
+ NEXUS_JWT_TOKEN=your_jwt_token_here
358
+
359
+ # Optional
360
+ NEXUS_OUTPUT_FORMAT=json # json, yaml, table, text
361
+ NEXUS_STREAMING=true # Enable real-time streaming
362
+ NEXUS_LOG_LEVEL=info # debug, info, warn, error
363
+ NEXUS_CACHE_ENABLED=true # Enable response caching
364
+ NEXUS_CACHE_TTL=300000 # Cache TTL in ms (5 min)
365
+ NEXUS_REQUEST_TIMEOUT=30000 # Request timeout in ms
366
+ NEXUS_MAX_RETRIES=3 # Max retry attempts
367
+ ```
368
+
369
+ ### Configuration Files
370
+
371
+ **Global config**: `~/.nexus/config.toml`
372
+ ```toml
373
+ [services]
374
+ api_url = "https://your-nexus-api.com"
375
+ timeout = 30000
376
+
377
+ [auth]
378
+ type = "api-key"
379
+ api_key = "${NEXUS_API_KEY}"
48
380
 
49
- See the [main documentation](../../README.md) for complete configuration options.
381
+ [output]
382
+ format = "json"
383
+ color = true
384
+ streaming = true
50
385
 
51
- ## Development
386
+ [plugins]
387
+ directory = "~/.nexus/plugins"
388
+ auto_update = false
389
+ ```
390
+
391
+ **Workspace config**: `.nexus.toml`
392
+ ```toml
393
+ [project]
394
+ name = "my-project"
395
+ default_service = "graphrag"
396
+
397
+ [commands]
398
+ # Custom command aliases
399
+ deploy = "workflow run ./deploy.yaml"
400
+ test = "agent task 'Run all tests and report coverage'"
401
+ ```
402
+
403
+ ---
404
+
405
+ ## Plugin Development
406
+
407
+ Create powerful extensions with the Nexus SDK.
408
+
409
+ ### Quick Start
52
410
 
53
411
  ```bash
412
+ # Create new plugin
413
+ npx @adverant-nexus/sdk create my-plugin
414
+ cd my-plugin
415
+
54
416
  # Install dependencies
55
417
  npm install
56
418
 
57
- # Build package
419
+ # Build and link
58
420
  npm run build
421
+ nexus plugin install ./dist
422
+ ```
423
+
424
+ ### Example Plugin
425
+
426
+ ```typescript
427
+ import {
428
+ NexusPlugin,
429
+ command,
430
+ option,
431
+ PluginContext
432
+ } from '@adverant-nexus/sdk';
433
+
434
+ export default class AnalyticsPlugin extends NexusPlugin {
435
+ name = 'analytics';
436
+ version = '1.0.0';
437
+ description = 'Custom analytics commands';
438
+
439
+ @command('report', 'Generate analytics report')
440
+ @option('--period <days>', 'Report period in days', '30')
441
+ @option('--format <type>', 'Output format', 'table')
442
+ async generateReport(ctx: PluginContext) {
443
+ const { period, format } = ctx.options;
444
+
445
+ // Access Nexus services
446
+ const analytics = await ctx.services.get('analytics');
447
+ const data = await analytics.getReport({ days: parseInt(period) });
448
+
449
+ // Format and return
450
+ return ctx.format(data, format);
451
+ }
452
+ }
453
+ ```
454
+
455
+ ---
59
456
 
60
- # Run in development mode
61
- npm run dev
457
+ ## Contributing
458
+
459
+ We welcome contributions! Nexus CLI is open source and community-driven.
460
+
461
+ ### Getting Started
462
+
463
+ ```bash
464
+ # Fork and clone
465
+ git clone https://github.com/YOUR_USERNAME/Adverant-Nexus-CLI.git
466
+ cd Adverant-Nexus-CLI
467
+
468
+ # Install dependencies
469
+ npm install
470
+
471
+ # Build all packages
472
+ npm run build
62
473
 
63
474
  # Run tests
64
475
  npm test
476
+
477
+ # Run in development
478
+ npm run dev:cli
65
479
  ```
66
480
 
481
+ ### Development Guidelines
482
+
483
+ - **TypeScript**: All code must be TypeScript with strict mode
484
+ - **Testing**: Add tests for new features
485
+ - **Commits**: Use [Conventional Commits](https://www.conventionalcommits.org/)
486
+ - **PRs**: Include description, tests, and documentation updates
487
+
488
+ See [CONTRIBUTING.md](https://github.com/adverant/Adverant-Nexus-CLI/blob/main/CONTRIBUTING.md) for detailed guidelines.
489
+
490
+ ---
491
+
67
492
  ## Documentation
68
493
 
69
- - [Main README](../../README.md) - Complete documentation
70
- - [Contributing Guidelines](../../CONTRIBUTING.md)
71
- - [API Documentation](../../docs/)
494
+ - [Full Documentation](https://docs.adverant.ai/nexus-cli)
495
+ - [API Reference](https://docs.adverant.ai/nexus-cli/api)
496
+ - [Plugin SDK Guide](https://docs.adverant.ai/nexus-cli/plugins)
497
+ - [Configuration Guide](https://docs.adverant.ai/nexus-cli/config)
498
+
499
+ ---
500
+
501
+ ## Security
502
+
503
+ Security is a top priority. See [SECURITY.md](https://github.com/adverant/Adverant-Nexus-CLI/blob/main/SECURITY.md) for:
504
+ - Reporting vulnerabilities
505
+ - Security best practices
506
+ - Credential management
507
+
508
+ ---
72
509
 
73
510
  ## License
74
511
 
75
- MIT © Adverant AI
512
+ MIT License - see [LICENSE](https://github.com/adverant/Adverant-Nexus-CLI/blob/main/LICENSE) for details.
513
+
514
+ ---
515
+
516
+ ## Acknowledgments
517
+
518
+ Built with these amazing open source projects:
519
+
520
+ - [Commander.js](https://github.com/tj/commander.js/) - CLI framework
521
+ - [Inquirer.js](https://github.com/SBoudrias/Inquirer.js/) - Interactive prompts
522
+ - [Chalk](https://github.com/chalk/chalk) - Terminal styling
523
+ - [Axios](https://github.com/axios/axios) - HTTP client
524
+ - [Zod](https://github.com/colinhacks/zod) - Schema validation
525
+ - [MCP SDK](https://github.com/anthropics/mcp) - Model Context Protocol
526
+
527
+ ---
528
+
529
+ <div align="center">
530
+
531
+ **Built with love by [Adverant](https://adverant.ai)**
532
+
533
+ [Website](https://adverant.ai) &#8226; [Documentation](https://docs.adverant.ai) &#8226; [Twitter](https://twitter.com/adverant) &#8226; [Discord](https://discord.gg/adverant)
534
+
535
+ </div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adverant-nexus/cli",
3
- "version": "3.0.0",
3
+ "version": "3.0.1",
4
4
  "description": "World-class CLI for Adverant-Nexus - Surpassing Claude Code and Gemini CLI",
5
5
  "main": "dist/index.js",
6
6
  "type": "module",