@codestate/cli
Version 1.0.11 - CLI interface for CodeState - A powerful development environment management tool
🚀 What's New in v1.0.11
$3
-
Cross-Platform Terminal Execution Modes: OS-aware terminal execution with intelligent mode selection
-
Same-Terminal Mode: Scripts run in tabs within a single terminal (macOS + Windows Terminal)
-
Multi-Terminal Mode: Each script runs in separate terminal windows
-
IDE Mode: Reserved for IDE extension integration
-
OS-Aware CLI: Automatically shows/hides options based on platform capabilities
-
Windows Terminal Support: Full Windows Terminal (
wt) integration for tab creation
- Automatic detection of Windows Terminal availability
- Programmatic tab creation using
wt new-tab commands
- Support for working directories and tab titles
- Fallback to multi-terminal mode when Windows Terminal unavailable
-
Enhanced macOS Terminal Support: Improved AppleScript-based tab creation
- Uses System Events for reliable tab creation in Terminal.app
- Better error handling and debugging capabilities
- Comprehensive logging for tab creation process
-
Script Filtering by IDs: Enhanced script management capabilities
-
GetScripts use case now supports filtering by script IDs
- Efficient individual script fetching for specific ID lists
- Maintains backward compatibility with existing filtering options
$3
-
OS Detection Integration: CLI now uses OS detection service for platform-aware features
- Automatic platform detection and capability assessment
- OS-specific execution mode filtering in CLI commands
- Enhanced terminal collection creation/update with OS-aware options
-
Terminal Collection Execution Modes: Enhanced terminal collection management
-
executionMode field added to terminal collections (
'ide' | 'same-terminal' | 'multi-terminal')
- Backward compatibility with default
same-terminal mode
- CLI commands updated to show OS-appropriate options
-
Cross-Platform Terminal Handling: Unified terminal spawning across platforms
- macOS: AppleScript System Events for tab creation
- Windows: Windows Terminal (
wt) for tab creation
- Linux: Multi-terminal fallback (no reliable tab support)
$3
-
Enhanced Terminal Collection Commands: Improved terminal collection management
-
codestate terminals create now shows OS-appropriate execution modes
-
codestate terminals update filters execution modes based on platform capabilities
- Better error handling and user feedback for terminal operations
-
Comprehensive Logging: Enhanced debugging and monitoring
- Detailed logging for terminal tab creation processes
- OS detection logging with capability explanations
- Windows Terminal command logging with formatted output
- AppleScript execution logging with error handling
-
Improved Error Handling: Better user experience with platform-specific error messages
- Clear error messages for unsupported terminal operations
- Graceful fallback when terminal capabilities are unavailable
- Enhanced validation for OS-specific features
$3
-
Linux Terminal Issues: Fixed multi-terminal mode closing automatically despite
closeTerminalAfterExecution: false - Proper use of
-hold flags for Linux terminals
- Better terminal spawning method selection
-
Linux Same-Terminal Mode: Fixed same-terminal mode not creating tabs and only running first script
- Implemented Linux-specific tab creation logic
- Support for GNOME Terminal, Konsole, XFCE Terminal, MATE Terminal, and Terminator
- Proper fallback to sequential execution for unsupported terminals
-
Terminal Collection Execution: Fixed terminal collection execution issues
- Proper handling of
closeAfterExecution flag
- Better command building without forced exit
- Enhanced error handling and logging
🚀 What's New in v1.0.9
$3
-
Terminal Collection Update: Complete terminal collection management capabilities
-
codestate terminals update [name] - Update terminal collections by name with interactive prompts
-
codestate terminals update - Interactive TUI for selecting and updating terminal collections
- Support for updating name, root path, lifecycle events, script references, and close behavior
- Name-to-ID resolution with automatic handling of multiple matches
- Comprehensive field selection with current value display and validation
-
Enhanced Architecture: Complete migration to use case-based architecture
- All terminal collection operations now use proper use cases instead of direct service calls
- Better separation of concerns: CLI/TUI → Use Cases → Services → Repositories
- Improved type safety with proper TypeScript interfaces
- Enhanced error handling and user feedback
$3
-
Script Lifecycle Integration: Enhanced script creation with lifecycle events
- Interactive lifecycle event selection ('open', 'resume', 'none') during script creation
- Lifecycle filtering for script listing and execution commands
- Updated CLI help text with comprehensive lifecycle options
-
Enhanced Filtering: Improved filtering capabilities across all commands
- Lifecycle-based filtering for scripts and terminal collections
- Root path filtering with current directory support
- Multiple filter combination support for advanced use cases
-
Better Error Handling: Improved user experience with better error messages
- Graceful handling of empty script lists during updates
- Clear error messages for missing resources
- Comprehensive validation for user inputs
🚀 What's New in v1.0.8
$3
-
Script Lifecycle Events: Enhanced script management with lifecycle support
- Interactive lifecycle event selection during script creation
- Lifecycle filtering for script listing and execution
- Support for 'open', 'resume', and 'none' lifecycle events
🚀 What's New in v1.0.6
$3
-
Comprehensive CLI Filtering: Advanced filtering options for sessions list command
-
--root-path - Filter sessions by project root path
-
--tags - Filter by comma-separated tags (e.g.,
--tags "feature,development")
-
--search - Search in session names and notes
-
--showAll - Display full session data including terminal collections and scripts
- Support for combining multiple filters (e.g.,
--showAll --tags "feature")
-
SessionWithFullData Support: Display complete session data with terminal collections and scripts
- Shows terminal collections with their associated scripts
- Displays individual scripts with command counts
- Enhanced session information with full data loading
-
Enhanced Session Management: Full data loading capabilities for detailed session views
- Automatic loading of terminal collections and scripts when
--showAll is used
- Backward compatibility with existing session commands
$3
-
Advanced CLI Arguments: Robust argument parsing similar to scripts CLI
- Proper validation for required argument values
- Support for multiple argument combinations
- Enhanced error messages for invalid usage
-
Type Safety: Comprehensive TypeScript support
- Proper handling of SessionWithFullData interface
- Type-safe CLI argument handling
- Enhanced error handling and validation
$3
-
CLI Help System: Enhanced help with detailed examples
- Comprehensive help for all session subcommands
- Detailed examples for filtering and data loading
- Clear usage patterns and best practices
-
Session Terminal Restoration: Improved terminal command restoration
- Uses terminal service methods instead of manual spawning
- Better error handling and timeout management
- Consistent with TerminalCollectionService patterns
🚀 What's New in v1.0.5
$3
-
Complete UUID Migration: All entities (scripts, terminal collections, sessions) now use consistent UUID-based file naming
-
Enhanced Windows Terminal Support: Added detection for Windows Terminal, PowerShell, WSL, Git Bash, and more
-
Improved File Storage Strategy: Atomic writes with backup files for all data operations
-
Better Linux Terminal Handling: Resolved terminal spawning conflicts on Linux systems
$3
-
Unified File Naming:
{uuid}.json format for all entity types
-
Enhanced Terminal Detection: OS-aware terminal spawning for Windows, macOS, and Linux
-
Robust Error Handling: Better backup file management and cleanup
-
Performance Improvements: Direct UUID lookups instead of path-based searches
🌟 CLI Features
- Script Management: Create, update, delete, and manage development scripts
- Session Management: Save and resume development sessions with advanced filtering
- Configuration Management: Export, import, and manage settings
- Terminal Collections: Group and execute related terminal commands
- Git Integration: Status checking, stash management, commit operations
- IDE Integration: Multi-IDE support for project and file management
- Cross-Platform Support: Works seamlessly on Windows, macOS, and Linux
- Advanced Filtering: Filter sessions by path, tags, search terms, and load full data
Overview
CodeState CLI provides a comprehensive command-line interface for managing your development context, including scripts, sessions, configurations, and git operations. It features both traditional CLI commands and an interactive TUI (Text User Interface) for enhanced user experience.
Features
$3
-
Create Scripts: Define reusable development scripts with interactive prompts
-
Update Scripts: Modify existing scripts with ease
-
Delete Scripts: Remove scripts by ID or root path
-
List Scripts: View all scripts or filter by project
-
Import/Export: Share scripts across environments
-
Resume Scripts: Execute saved scripts with full context
$3
-
Save Sessions: Capture your current development state including open files, git status, and terminal commands
-
Resume Sessions: Restore previous development contexts with file positions and terminal state
-
List Sessions: View all saved sessions with metadata
-
Update Sessions: Modify session metadata and notes
-
Delete Sessions: Clean up old sessions
$3
-
Show Config: Display current configuration settings
-
Update Config: Modify settings interactively
-
Export Config: Backup your configuration to file
-
Import Config: Restore configuration from backup
-
Reset Config: Restore default settings
$3
-
Git Status: Check repository state and changes
-
Stash Management: Create, list, and apply stashes
-
Commit Changes: Stage and commit modifications
-
Dirty Data: Track uncommitted changes
$3
-
Multi-IDE Support: Works with VS Code, WebStorm, and more
-
Open Projects: Launch projects in your preferred IDE
-
File Management: Open specific files in IDE
$3
-
Create Terminal Collections: Group related terminal commands
-
Execute Collections: Run multiple commands in sequence
-
List Collections: View all terminal collections
-
Show Collections: Get detailed information about specific collections
-
Delete Collections: Remove terminal collections with interactive TUI
-
Manage Collections: Update and delete collections
$3
-
Comprehensive Reset: Reset sessions, scripts, terminals, config, or all data
-
Interactive Reset: User-friendly interface with confirmation prompts
-
CLI Flags: Support for
--all,
--sessions,
--scripts,
--terminals,
--config flags
$3
-
CLI Spinners: Professional loading animations for all operations
- Visual feedback during long-running commands
- Smooth 10-frame animations with consistent timing
- Cross-platform compatibility (Windows, Linux, macOS)
-
Professional Logging: Clean, consistent output formatting
- Automatic symbol addition (✅, ❌, ⚠️) by logger methods
- User-friendly error messages without technical details
- Consistent experience across all CLI commands
Installation
``bash
npm install -g @codestate/cli
`
Quick Start
`bash
Initialize CodeState in your project
codestate config show
Create your first script
codestate scripts create
Save your current development session
codestate session save
List all your scripts
codestate scripts show
`
Command Reference
$3
`
bash
Create a new script
codestate scripts createShow all scripts
codestate scripts showShow scripts for specific project
codestate scripts show-by-path /path/to/projectUpdate a script
codestate scripts update Delete a script
codestate scripts delete Delete all scripts for a project
codestate scripts delete-by-root-path /path/to/projectExport scripts to file
codestate scripts export --output scripts.jsonImport scripts from file
codestate scripts import --input scripts.jsonResume a script
codestate scripts resume
`
$3
`
bash
Save current session
codestate session saveList all sessions
codestate session listList sessions with advanced filtering
codestate session list --showAll
codestate session list --root-path .
codestate session list --tags "feature,development"
codestate session list --search "auth"
codestate session list --showAll --tags "feature"Resume a session
codestate session resume Update session metadata
codestate session update Delete a session
codestate session delete
`
$3
`
bash
Show current configuration
codestate config showUpdate configuration
codestate config updateExport configuration
codestate config export --output config.jsonImport configuration
codestate config import --input config.jsonReset to defaults
codestate config reset
`
$3
`
bash
List all terminal collections
codestate terminals listCreate a new terminal collection
codestate terminals createGet details of a specific collection
codestate terminals show Execute a terminal collection
codestate terminals resume Update a terminal collection (NEW!)
codestate terminals update [collection-name]Delete a terminal collection
codestate terminals delete [collection-name]Export terminal collections
codestate terminals exportImport terminal collections
codestate terminals import
`
$3
`
bash
Reset everything (interactive)
codestate resetReset everything (non-interactive)
codestate reset --allReset specific data types
codestate reset --sessions
codestate reset --scripts
codestate reset --terminals
codestate reset --config
`
Interactive Mode
CodeState CLI includes an interactive TUI for enhanced user experience:
`
bash
Launch interactive mode for scripts
codestate scriptsLaunch interactive mode for sessions
codestate sessionLaunch interactive mode for configuration
codestate configLaunch interactive mode for terminal collections
codestate terminals
`
Examples
$3
`
bash
codestate scripts create
Follow the prompts to create a script:
- Name: setup-project
- Content: npm install && npm run build
- Root Path: /path/to/your/project
`
$3
`
bash
Save current state including open files, git status, and scripts
codestate session save
Enter session name: feature-development
Session saved with ID: abc123
`
$3
`
bash
List available sessions
codestate session listResume a specific session
codestate session resume abc123
This will restore your development environment
`
$3
`
bash
View current settings
codestate config showUpdate settings interactively
codestate config update
Follow prompts to modify configuration
`
$3
`
bash
List all terminal collections
codestate terminals listCreate a new terminal collection
codestate terminals create
Follow prompts to create a collection with scripts
Update an existing terminal collection
codestate terminals update my-collection
Interactive prompts to update name, lifecycle, scripts, etc.
Execute a collection of commands
codestate terminals resume setup-project
This will run all commands in the collection sequentially
`
$3
`
bash
Interactive reset with confirmation prompts
codestate resetReset everything without prompts
codestate reset --allReset only sessions
codestate reset --sessions
`
CLI Spinners and Enhanced UX
$3
CodeState CLI includes smooth, professional loading animations for all operations:- Visual Feedback: Spinners show progress during long-running operations
- Consistent Timing: 10-frame animations with 80ms refresh rate
- Cross-Platform: Works seamlessly on Windows, Linux, and macOS
- State Management: Support for start, update, succeed, and fail states
$3
All CLI output is designed for professional use:- Automatic Symbols: Logger methods automatically add appropriate symbols
-
logger.log()
→ ✅ Success messages
- logger.error()
→ ❌ Error messages
- logger.warn()
→ ⚠️ Warning messages
- Clean Messages: User-friendly output without technical metadata
- Consistent Formatting: Professional appearance across all commands$3
`
bash
Terminal collection creation with spinner
codestate terminals create
Shows: 🚀 Creating terminal collection...
Then: ✅ Terminal collection created successfully!
Script execution with progress updates
codestate scripts resume my-script
Shows: ⚡ Executing script...
Then: ✅ Script completed successfully!
Session loading with visual feedback
codestate session list
Shows: 📋 Loading sessions...
Then: ✅ Sessions loaded
`
Configuration
CodeState CLI uses a configuration file to store settings. The default location is:
- Windows:
%APPDATA%/codestate/config.json
- macOS: ~/Library/Application Support/codestate/config.json
- Linux: ~/.config/codestate/config.json
$3
`
json
{
"ide": "vscode",
"version": "1.0.0",
"encryption": {
"enabled": false
},
"storagePath": "~/.codestate",
"logger": {
"level": "LOG",
"sinks": ["file"]
},
"experimental": {},
"extensions": {}
}
`
Integration with IDEs
CodeState CLI integrates with popular IDEs:
- VS Code: Open projects and files directly
- Install the CodeState IDE Extension for seamless IDE integration
- WebStorm/IntelliJ: Launch projects in JetBrains IDEs
- Sublime Text: Open files in Sublime
- Vim/Neovim: Open files in terminal editors
> Tip: You can use both the CLI and IDE extension for most tasks. The CLI is great for terminal workflows and automation, while the IDE extension provides a native VS Code experience for managing your development context.
Error Handling
CodeState CLI provides comprehensive error handling:
- Graceful Error Messages: Clear, actionable error messages
- Exit Codes: Proper exit codes for automation
- Logging: Detailed logging for debugging
- Recovery: Automatic recovery from common errors
Development
This package is part of the CodeState monorepo. For development setup and contributing, see the main CodeState repository.
$3
`
bash
Clone the repository
git clone https://github.com/codestate-cs/code-state-library.git
cd code-state-libraryInstall dependencies
npm installBuild CLI package
npm run build:cliRun in development mode
npm run dev
``
Contributing
We welcome contributions! Please see our Contributing Guide for details.
License
MIT