codestate-cli/README.md

CodeState CLI - Configuration, Script, and Git Management

# CodeState CLI

A powerful command-line interface for CodeState - a developer context engine for saving and resuming your full development environment.

Visit [codestate.dev](https://www.codestate.dev/) for more information about CodeState.

## Version 1.4.6 Updates

### What's New
- **Enhanced Functionality**: Improved CLI commands and interface consistency
- **Better Integration**: Updated to work with core package v1.4.5
- **Build Improvements**: Enhanced build system and dependency management
- **Package Updates**: Updated to v1.4.5 with improved stability

### Changes from v1.4.2
- 🔧 **Core Integration**: Updated to use codestate-core v1.4.5
- 🏗️ **Build Improvements**: Enhanced build system with better dependency resolution
- 📦 **Package Updates**: Updated to v1.4.5 with improved functionality

## 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

### 🚀 Script Management
- **Create Scripts**: Define reusable development scripts
- **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

### 💾 Session Management
- **Save Sessions**: Capture your current development state
- **Resume Sessions**: Restore previous development contexts
- **List Sessions**: View all saved sessions
- **Update Sessions**: Modify session metadata
- **Delete Sessions**: Clean up old sessions

### ⚙️ Configuration Management
- **Show Config**: Display current configuration
- **Update Config**: Modify settings interactively
- **Export Config**: Backup your configuration
- **Import Config**: Restore configuration from backup
- **Reset Config**: Restore default settings

### 🔧 Git Integration
- **Git Status**: Check repository state
- **Stash Management**: Create, list, and apply stashes
- **Commit Changes**: Stage and commit modifications
- **Dirty Data**: Track uncommitted changes

### 🎯 IDE Integration
- **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

### 🖥️ Terminal Collections
- **Create Terminal Collections**: Group related terminal commands
- **Execute Collections**: Run multiple commands in sequence
- **List Collections**: View all terminal collections
- **Manage Collections**: Update and delete collections

## 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

### Scripts Commands

```bash
# Create a new script
codestate scripts create

# Show all scripts
codestate scripts show

# Show scripts for specific project
codestate scripts show --root-path /path/to/project

# Update a script
codestate scripts update <script-id>

# Delete a script
codestate scripts delete <script-id>

# Delete all scripts for a project
codestate scripts delete-by-root-path /path/to/project

# Export scripts to file
codestate scripts export --output scripts.json

# Import scripts from file
codestate scripts import --input scripts.json
```

### Session Commands

```bash
# Save current session
codestate session save

# List all sessions
codestate session list

# Resume a session
codestate session resume <session-id>

# Update session metadata
codestate session update <session-id>

# Delete a session
codestate session delete <session-id>
```

### Configuration Commands

```bash
# Show current configuration
codestate config show

# Update configuration
codestate config update

# Export configuration
codestate config export --output config.json

# Import configuration
codestate config import --input config.json

# Reset to defaults
codestate config reset
```

### Terminal Collection Commands

```bash
# List all terminal collections
codestate terminals list

# Get details of a specific collection
codestate terminals get <collection-name>

# Execute a terminal collection
codestate terminals execute <collection-name>
```

## Interactive Mode

CodeState CLI includes an interactive TUI for enhanced user experience:

```bash
# Launch interactive mode for scripts
codestate scripts

# Launch interactive mode for sessions
codestate session

# Launch interactive mode for configuration
codestate config

# Launch interactive mode for terminal collections
codestate terminals
```

## Examples

### Creating a Development Script

```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
```

### Saving a Development Session

```bash
# Save current state including open files, git status, and scripts
codestate session save
# Enter session name: feature-development
# Session saved with ID: abc123
```

### Resuming a Session

```bash
# List available sessions
codestate session list

# Resume a specific session
codestate session resume abc123
# This will restore your development environment
```

### Managing Configuration

```bash
# View current settings
codestate config show

# Update settings interactively
codestate config update
# Follow prompts to modify configuration
```

### Working with Terminal Collections

```bash
# List all terminal collections
codestate terminals list

# Execute a collection of commands
codestate terminals execute setup-project
# This will run all commands in the collection sequentially
```

## 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`

### Configuration Options

```json
{
  "defaultIDE": "vscode",
  "scriptsDirectory": "~/.codestate/scripts",
  "sessionsDirectory": "~/.codestate/sessions",
  "gitAutoCommit": false,
  "sessionAutoSave": true
}
```

## Integration with IDEs

CodeState CLI integrates with popular IDEs:

- **VS Code**: Open projects and files directly
  - Install the [CodeState IDE Extension](https://marketplace.visualstudio.com/items?itemName=karthikchinasani.codestate-ide) for seamless IDE integration - manage scripts, sessions, and configurations directly from VS Code
- **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. However, for saving sessions, we recommend using the IDE extension as it can capture file contents and open files, while the CLI can only save metadata. The CLI is great for terminal workflows and automation, while the IDE extension provides a native VS Code experience for managing your development context.

## Development

This package is part of the CodeState monorepo. For development setup, see the main [CodeState repository](https://github.com/codestate-cs/code-state-library).

### Building from Source

```bash
# Clone the repository
git clone https://github.com/codestate-cs/code-state-library.git
cd code-state-library

# Install dependencies
npm install

# Build CLI package
npm run build:cli

# Run in development mode
npm run dev
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/codestate-cs/code-state-library/blob/main/CONTRIBUTING.md) for details.

## License

MIT