nexus
/
nip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
nip/docs/shell-guide.md

4.7 KiB
Raw Blame History

NIP Shell - Interactive Package Management

The NIP Shell provides a powerful, interactive command-line interface for managing packages with advanced features like context-aware prompting, intelligent command completion, and session management.

Getting Started

Launch the interactive shell:

nip shell

You'll see a context-aware prompt showing your current track:

🟢 nip>

Prompt Indicators

The shell prompt provides visual feedback about your current context:

  • 🟢 nip> - Stable track
  • 🟡 nip:testing> - Testing track
  • 🔴 nip:dev> - Development track
  • ⚪ nip:lts> - LTS track
  • ⚡ - Active transaction indicator

Command Categories

📦 Package Management

  • install <package> - Install a package
  • remove <package> - Remove a package
  • search <query> - Search for packages
  • list [pattern] - List installed packages
  • show <package> - Show package information

⚡ Transaction Management

  • plan - Show current transaction plan
  • commit - Commit pending transaction
  • rollback - Rollback last transaction
  • status - Show system status

🔧 Session Management

  • track [name] - Switch tracks or show current track
  • session save <name> - Save current session
  • session load <name> - Load saved session
  • session list - List all saved sessions

🔒 Security & Integrity

  • verify <package> - Verify package integrity
  • diagnose <cid> - Run forensic diagnosis
  • attest <package> - Create attestation
  • trust <key> - Manage trust levels

🛠️ Utility Commands

  • help [command] - Show help information
  • history - Show command history
  • clear - Clear screen
  • exit - Exit shell

Smart Features

Intelligent Help System

Get categorized help:

🟢 nip> help

Get detailed help for specific commands:

🟢 nip> help install
Command: install
Description: Install a package
Usage: install <package> [options]
Aliases: add
Examples:
  install firefox
  install gcc --stream testing

Command Suggestions

The shell provides smart suggestions for typos:

🟢 nip> instal
Error: Unknown command: 'instal'
Did you mean: install?

Track Management

Switch between different package tracks:

🟢 nip> track testing
Switched from stable to testing
🟡 nip:testing>

View current status:

🟡 nip:testing> status
NIP Shell Status:
  Track: testing
  Channels: main, community
  Flavor: nexusos
  Toolchain: latest
  Working Dir: /
  No active transaction
  Session Created: 2025-08-31 00:50
  Last Used: 2025-08-31 00:50

Example Session

Here's a typical workflow using the NIP shell:

# Launch the shell
$ nip shell
NIP Shell v0.1.0 - Interactive Package Management
Type 'help' for available commands, 'exit' to quit

# Check current status
🟢 nip> status
NIP Shell Status:
  Track: stable
  Channels: main, community
  Flavor: nexusos
  ...

# Switch to testing track for newer packages
🟢 nip> track testing
Switched from stable to testing

# Search for a package
🟡 nip:testing> search firefox
[Package search results would appear here]

# Get detailed help for install command
🟡 nip:testing> help install
Command: install
Description: Install a package
Usage: install <package> [options]
...

# Save current session for later
🟡 nip:testing> session save work-session
Session saved: work-session

# Exit the shell
🟡 nip:testing> exit
Session saved. Goodbye!

Advanced Features

Session Persistence

  • Sessions automatically save your track, channels, and preferences
  • Named sessions allow you to switch between different work contexts
  • Session history is preserved across shell restarts

Command History

  • Full command history with persistent storage
  • History navigation and search (coming soon)
  • Command completion based on history (coming soon)

Error Recovery

  • Intelligent error messages with suggestions
  • Graceful handling of invalid commands
  • Context-sensitive help for troubleshooting

Tips and Tricks

  1. Use aliases: Many commands have short aliases (e.g., ls for list, st for status)

  2. Tab completion: TAB completion for commands and arguments (coming soon)

  3. Command chaining: Plan complex operations before committing (coming soon)

  4. Session management: Save different configurations for different projects

  5. Help system: Use help <command> to learn about any command in detail

Future Features

  • TAB completion for commands, packages, and paths
  • Command history search and navigation
  • Macro system for complex command sequences
  • Real-time package monitoring and notifications
  • Integration with external tools and editors

The NIP Shell represents the future of package management interfaces - intelligent, context-aware, and designed for productivity.