FlowCLI Cover

User Guide

Introduction

FlowCLI is a Command Line Interface (CLI) app for managing tasks and projects, optimised for fast, fully keyboard-driven workflows. It offers two convenient ways to work: inline commands for power users who want to type everything at once, and interactive mode for guided step-by-step input. Track priorities, deadlines and statuses of your projects, filter and sort instantly, then export the current view to a TXT file to save your changes. If you’re a fast typer, FlowCLI is perfect for you - save hours on project management as it gets your work done faster than click-heavy apps.

Quick Start

Ensure Java 17 is installed: java -version should report 17.x.
Download the latest flowcli.jar from here.
Run the application from a terminal in the same folder as the JAR:
```
java -jar flowcli.jar
```
You will see flowCLIs greetings, then you may begin typing the commands
Type help to see the list of commands.
FlowCLI will read commands until you enter bye. You can use either inline commands (full syntax) or interactive mode (just type the command name for guided input).

Important Notes

Data Persistence

✅ FlowCLI automatically saves your data! All projects and tasks are automatically saved to data/flowcli-data.txt when you exit with bye. When you reopen FlowCLI, your data is automatically loaded.

Additional features:

Data is saved in the same directory where you run flowcli.jar
If the data file is corrupted, FlowCLI will back it up and start fresh
You can still use export-tasks to create human-readable snapshots for reports or sharing

Features

General Command Format

FlowCLI supports two command modes to suit your preference:

Inline Commands: Provide all arguments in one line for quick execution

Commands are case-insensitive.
Projects are referenced by their index from list --all.
Task descriptions can contain spaces. Separate options from the description with --.
Deadlines use the YYYY-MM-DD format. Priorities accept low, medium, or high.

Interactive Mode: Get guided prompts for missing information

Type just the command name (like add, create, update) and FlowCLI will ask for each required detail
Perfect for learning commands or when you prefer step-by-step guidance
All the same validation and features apply

Both modes work identically - choose whichever feels more comfortable!

Create a project: `create-project <projectName> / create (interactive mode)`

Adds a new project. If you add a new project with the same name (any casing), FlowCLI reports a duplicate.

Project names can be wrapped in quotes (double " or single '). FlowCLI will automatically remove the surrounding quotes when storing the project name. Quotes are optional - you can use them for names with spaces, or omit them entirely.

create-project "Birthday Bash"
create-project 'Birthday Bash'
create-project Birthday Bash

All three examples above create projects Birthday Bash.

List projects or tasks: `list --all` or `list <projectIndex>` or `list (interactive mode)`

list --all shows all projects and their indices.
list <projectIndex> shows the tasks under a specific project.

list 1

Add a task: `add-task <projectIndex> <description> [--priority <level>] [--deadline <YYYY-MM-DD>]` or `add (interactive mode)`

Adds a task under an existing project with optional priority and deadline. Priority defaults to medium, deadline defaults to none.

Structure is felxible such that you can also input --deadline first before --priority as long as the input are valid

add-task 1 Hang fairy lights --priority high --deadline 2025-01-31

Common mistakes and fixes:

“Project index is out of range”: Run list --all and use the shown index (starts at 1).
“Invalid priority value”: Use one of low, medium, high (case-insensitive).
“Invalid date format”: Use YYYY-MM-DD (e.g., 2025-11-15).

Update a task: `update-task <projectIndex> <taskIndex> [--description <desc>] [--deadline <YYYY-MM-DD|none>] [--priority <level>]` or `update (interactive mode)`

Edits the specified task in place. You can change one field or combine multiple options in the same command.

--description replaces the task description.
--deadline updates the due date; pass none (or clear) to remove an existing deadline.
--priority accepts low, medium, or high.

update-task 1 2 --description "Assemble party bags" --deadline 2025-02-15 --priority medium
update-task 1 3 --deadline none

Common mistakes and fixes:

“Task index is out of range”: Use list <projectIndex> to see valid task numbers.
“Invalid date format”: Use YYYY-MM-DD, or none to clear the deadline.
“Invalid priority value”: Use low, medium, or high.

Mark or unmark a task: `mark <projectIndex> <taskIndex>` / `unmark <projectIndex> <taskIndex>` or `mark/unmark (interactive mode)`

Marks the specified task (based on the number shown in list <projectIndex>) as done or not done.

mark 1 2

Delete items: `delete-project <projectIndex> --confirm` or `delete-task <projectIndex> <taskIndex>` or `delete (interactive mode)`

delete-project <projectIndex> --confirm removes the entire project and all its tasks.
delete-task <projectIndex> <taskIndex> removes the indexed task from that project.

delete-task 1 3
delete-project 1 --confirm

Sort tasks across projects: `sort-tasks <--deadline|--priority> <ascending|descending>` or `sort (interactive mode)`

Displays every task from every project in the requested order and remembers this view for exporting.

sort-tasks --deadline ascending

Common mistakes and fixes:

“Invalid sort field”: Use --deadline or --priority.
“Invalid sort order”: Use ascending or descending.

Filter tasks across projects: `filter-tasks --priority <value>` or `filter (interactive mode)`

Shows only tasks that match the chosen priority. The filtered view can be exported directly.

filter-tasks --priority high

Common mistakes and fixes:

“Invalid priority value”: Use low, medium, or high.

Get project status: `status <projectIndex>` or `status --all` or `status (interactive mode)`

status <projectIndex> shows the completion status for a specific project.
status --all shows the completion status for all projects.

status 1
status --all

Export tasks: `export-tasks <filename>.txt [projectIndex] [filter-tasks --priority <value>] [sort-tasks <--deadline|--priority> <order>]` or `export (interactive mode)`

Saves tasks to a plain-text file with flexible export options.

Export behavior:

With --all flag: Always exports all tasks from all projects
```
export-tasks all-tasks.txt --all
```
With project index: Exports only tasks from the specified project
```
export-tasks party-plan.txt 1
```

With filter/sort in command: Exports tasks matching the specified criteria

export-tasks high-priority.txt filter-tasks --priority high sort-tasks --deadline ascending

Without any parameters:
- If you previously ran sort-tasks or filter-tasks, exports that cached view
- If no cached view exists (or you used list command), exports all tasks
- To force exporting all tasks, use the --all flag

Clearing the cached view: The cached sorted/filtered view is automatically cleared when you use list commands:

list --all clears the cached view
list <projectIndex> clears the cached view

Notes:

Files are written to your current working directory by default. Use absolute or relative paths to choose a location.
- If the path contains spaces, wrap it in quotes: export-tasks "My Reports/tasks.txt"
Existing files with the same name will be overwritten.
Inline mode requires the .txt extension in the filename. In interactive mode, entering the name without .txt will auto-append .txt.

Common mistakes and fixes:

“Invalid filename”: Avoid illegal characters and ensure the name ends with .txt.
“Export failed: Directory does not exist”: Create the folder or use an existing path.
“Export failed: Permission denied”: Export to a writable location (e.g., home directory).
“No tasks to export”: Broaden scope by removing filters or exporting all tasks.

Interactive mode options: After entering a filename, choose to export: all tasks, a specific project, filtered tasks, sorted tasks, or filtered+sorted tasks, then confirm.

Export file format example: When you export tasks, FLowCLI creates a plain text file like this:

CS2113T Project - high priority
============================================

[X] [H] Finalize DG (Due: 2025-11-10)
[ ] [H] Implement UI (Due: 2025-11-20)
[ ] [M] Write UG (Due: 2025-11-25)

Get help and exit: `help` / `bye`

help reprints the command summary inside the app.
bye exits FlowCLI.

Common Workflows

Here are some practical examples of how to combine commands for common use cases:

Daily Task Review

# Check what's urgent
filter-tasks --priority high
status --all

# Review and update a task
list 1
update-task 1 2 --deadline 2025-11-15
mark 1 1

Weekly Planning

# See all upcoming deadlines
sort-tasks --deadline ascending

# Export high-priority items for the week
export-tasks weekly-plan.txt filter-tasks --priority high sort-tasks --deadline ascending

Project Cleanup

# Check project status
status --all

# Mark completed tasks
mark 1 1
mark 1 3

# Remove finished tasks
delete-task 1 1

Custom Reports

# Create a report of medium-priority tasks
export-tasks medium-tasks.txt filter-tasks --priority medium

# Create a deadline-sorted report for a specific project
export-tasks project1-deadlines.txt 1 sort-tasks --deadline ascending

Testing Your Setup

Want to make sure FlowCLI is working perfectly? Follow these steps to test all features and get comfortable with the interface.

Quick Test Setup

Get started fast: Launch FlowCLI and try these basic commands to verify everything works:

# Start FlowCLI
java -jar flowcli.jar

# Get help (shows all available commands)
help

# Create your first project
create-project "My First Project"

# Try out interactive mode to create!
create

# Add a sample task
add-task 1 "Test task" --priority high --deadline 2025-12-31

# View your project
list --all

# Exit when done
bye

Comprehensive Testing Guide

For a thorough test of all FlowCLI features, use this sample dataset:

Sample Data Setup

# Create sample projects
create-project "CS2113T Project"
create-project "Internship Hunt"
create-project "Household Chores"
create-project "Fitness Plan"
create-project "Side Project - Website"

# Add tasks with various priorities and deadlines
add-task 1 "Finalize DG" --priority high --deadline 2025-11-10
add-task 1 "Implement UI" --priority high --deadline 2025-11-20
add-task 1 "Write UG" --priority medium --deadline 2025-11-25
add-task 1 "Prepare for Demo" --priority medium
add-task 1 "Review teammate PR" --priority low

add-task 2 "Update Resume" --priority high
add-task 2 "Apply to 5 companies" --priority medium --deadline 2025-11-15
add-task 2 "Research company A" --priority low
add-task 2 "Practice LeetCode" --priority medium

add-task 3 "Buy groceries" --priority medium --deadline 2025-10-29
add-task 3 "Clean room" --priority low
add-task 3 "Pay utility bill" --priority high --deadline 2025-11-01

add-task 4 "Go for run" --priority medium
add-task 4 "Meal prep for week" --priority low
add-task 4 "Go to gym" --priority medium

add-task 5 "Design homepage" --priority medium
add-task 5 "Set up database" --priority high --deadline 2025-12-01
add-task 5 "Draft 'About Me' page" --priority low

# Mark some tasks as complete
mark 1 1
mark 2 1
mark 3 3
mark 4 1

These are to build up the list of projects and tasks, with the necessary details. You can freely test out

sort/filter, delete, update, export

with these however you like.

Test All Commands

Now explore FlowCLI’s full capabilities:

View help anytime: Type help to see all commands and their formats
Try inline commands: Use full command syntax like add-task 1 "New task" --priority high
Explore interactive mode: Type just add, create, list, mark, unmark, update, delete, sort, filter, or export for guided input
Sort and filter: Try sort-tasks --deadline ascending or filter-tasks --priority high
Check status: Use status --all to see project completion overview
Export data: Run export-tasks my-tasks.txt to save your work

What to Expect

Inline commands execute immediately with all provided information
Interactive mode guides you step-by-step when you provide minimal input
Error messages help you fix mistakes and learn proper syntax
Help system provides comprehensive command reference

Troubleshooting Tips

JAR not found? Make sure the build completed successfully and you’re using the correct path
Command errors? Double-check project/task numbers exist with list --all
Interactive mode not working? Ensure you enter commands without arguments to trigger guided input

Troubleshooting

Common Errors and Solutions

“Project index is out of range”

Check available projects with list --all
Projects are numbered starting from 1
Make sure you’re using the correct index from the list output

“Task index is out of range”

Use list <projectIndex> to see all tasks in that project
Tasks are numbered starting from 1 within each project
Verify the task hasn’t been deleted already

“Export failed: Permission denied”

Ensure you have write permissions in the directory
Try exporting to a different location (e.g., your home directory)
On Windows, avoid system directories like C:\Windows

“Export failed: Directory does not exist”

Create the parent folders first or export to an existing path
Use a valid absolute or relative path (e.g., ~/exports/report.txt)

“Export failed due to filesystem error (read-only, disk full, etc.)”

Ensure the target drive/folder is writable and has free space
Try exporting to another drive or your home directory

“File is currently open or locked”

Close the exported file in other programs (Excel, text editors, etc.)
Try using a different filename
Wait a moment and try again

Interactive mode not triggering?

Ensure you type ONLY the command name (e.g., add not add-task)
Don’t include any arguments or flags to trigger interactive prompts
Commands that support interactive mode: create, add, list, mark, unmark, delete, update, sort, filter, export

“Invalid date format”

Dates must be in YYYY-MM-DD format (e.g., 2025-11-15)
Use 4-digit year, 2-digit month, 2-digit day
Separate with hyphens, not slashes

“Invalid priority value”

Priority must be one of: low, medium, or high
Case-insensitive (LOW, Low, low all work)
Cannot use abbreviations like l, m, h

“Unexpected extra parameters”

Commands like status and list expect only the documented arguments
Examples of errors:
- status 1 2 → Error: “Unexpected extra parameters: 2” → Use status 1
- list 1 extra → Error: “Unexpected extra parameters: extra” → Use list 1
Check the command format in help or the Command Summary table

“This command does not accept any parameters”

Commands like help and bye don’t take any arguments
Examples of errors:
- help extra → Use help (no arguments needed)
- bye extra → Use bye (no arguments needed)

Tips and Best Practices

Workflow Optimization

Start each session fresh: Use list --all to check what projects you have
Use descriptive project names: Makes filtering and organizing easier later
Set realistic deadlines: Helps with priority management and sorting
Export for reports: Use export to create human-readable snapshots for meetings, sharing, or backups
Combine filter + sort + export: Create custom reports for different contexts (meetings, weekly reviews, etc.)

Command Usage

Use interactive mode to learn: Great for remembering command syntax when starting out
Use inline mode for speed: Once you know the commands, inline is much faster
Leverage the help command: Type help anytime to see all available commands and their formats
Double-check indices: Always verify project/task numbers with list before deleting

Task Management

Mark tasks as done regularly: Helps track progress with the status command
Use priority levels strategically:
- high for urgent/important tasks
- medium for regular tasks
- low for nice-to-have items
Set deadlines wisely: Even if approximate, deadlines help with sorting and planning
Review status frequently: Use status --all to get a quick overview of all your projects

Export Strategies

Exports for sharing: Export creates human-readable files perfect for sharing with teammates or stakeholders
Filtered exports: Create focused task lists for specific needs (e.g., export-tasks meeting.txt filter-tasks --priority high)
Deadline-sorted exports: Great for weekly planning (e.g., export-tasks week.txt sort-tasks --deadline ascending)
Per-project exports: Export individual projects for team sharing or handoffs
Be explicit about paths: Use absolute/relative paths to control where files are saved
Overwrites: Export will overwrite files with the same name; pick unique names when needed

FAQ

Q: How do I transfer my tasks to another machine? A: FlowCLI stores tasks in data/flowcli-data.txt. Copy this file to the same location (relative to where you run the JAR) on the new machine. Alternatively, use export-tasks all_tasks.txt for a human-readable snapshot.

Q: Why do I get an error about an invalid index? A: Project and task indices must be valid numbers corresponding to the lists. Use list --all to see project indices and list <projectIndex> for task indices.

Q: What’s the difference between inline commands and interactive mode? A: Inline commands require you to type the full command with all arguments (e.g., add-task 1 "Buy groceries" --priority high). Interactive mode lets you type just the command name (e.g., add) and then guides you through each required input step-by-step. Both modes do exactly the same thing - choose whichever you prefer!

Command Summary

Action	Format	Example
Create project	`create-project <projectName>`	`create-project BirthdayBash`
List all projects	`list --all`	`list --all`
List tasks	`list <projectIndex>`	`list 1`
Add task	`add-task <projectIndex> <desc> [--priority <level>] [--deadline <YYYY-MM-DD>]`	`add-task 1 "Inflate balloons" --priority high --deadline 2024-06-15`
Update task	`update-task <projectIndex> <taskIndex> [--description <desc>] [--deadline <YYYY-MM-DD\\|none>] [--priority <level>]`	`update-task 1 1 --priority medium`
Mark / Unmark	`mark <projectIndex> <taskIndex>` / `unmark <projectIndex> <taskIndex>`	`mark 1 1`
Delete project	`delete-project <projectIndex> --confirm`	`delete-project 1 --confirm`
Delete task	`delete-task <projectIndex> <taskIndex>`	`delete-task 1 2`
Sort tasks	`sort-tasks <--deadline\\|--priority> <ascending\\|descending>`	`sort-tasks --priority descending`
Filter tasks	`filter-tasks --priority <value>`	`filter-tasks --priority medium`
Get status	`status <projectIndex>` / `status --all`	`status 1`
Export tasks	`export-tasks <filename>.txt [projectIndex] [filter-tasks ...] [sort-tasks ...]`	`export-tasks party-plan.txt 1`
Help / Exit	`help` / `bye`	`help`

Or, simply just use basic commands: create, list, add, update, mark/unmark, delete, sort, filter, status, export, help, bye, to easily trigger the interactive prompt

User Guide

Introduction

Quick Start

Important Notes

Data Persistence

Features

General Command Format

Create a project: create-project <projectName> / create (interactive mode)

List projects or tasks: list --all or list <projectIndex> or list (interactive mode)

Add a task: add-task <projectIndex> <description> [--priority <level>] [--deadline <YYYY-MM-DD>] or add (interactive mode)

Update a task: update-task <projectIndex> <taskIndex> [--description <desc>] [--deadline <YYYY-MM-DD|none>] [--priority <level>] or update (interactive mode)

Mark or unmark a task: mark <projectIndex> <taskIndex> / unmark <projectIndex> <taskIndex> or mark/unmark (interactive mode)

Delete items: delete-project <projectIndex> --confirm or delete-task <projectIndex> <taskIndex> or delete (interactive mode)

Sort tasks across projects: sort-tasks <--deadline|--priority> <ascending|descending> or sort (interactive mode)

Filter tasks across projects: filter-tasks --priority <value> or filter (interactive mode)

Get project status: status <projectIndex> or status --all or status (interactive mode)

Export tasks: export-tasks <filename>.txt [projectIndex] [filter-tasks --priority <value>] [sort-tasks <--deadline|--priority> <order>] or export (interactive mode)

Get help and exit: help / bye

Common Workflows

Daily Task Review

Weekly Planning

Project Cleanup

Custom Reports

Testing Your Setup

Quick Test Setup

Comprehensive Testing Guide

Sample Data Setup

Test All Commands

What to Expect

Troubleshooting Tips

Troubleshooting

Common Errors and Solutions

Tips and Best Practices

Workflow Optimization

Command Usage

Task Management

Export Strategies

FAQ

Command Summary

Create a project: `create-project <projectName> / create (interactive mode)`

List projects or tasks: `list --all` or `list <projectIndex>` or `list (interactive mode)`

Add a task: `add-task <projectIndex> <description> [--priority <level>] [--deadline <YYYY-MM-DD>]` or `add (interactive mode)`

Update a task: `update-task <projectIndex> <taskIndex> [--description <desc>] [--deadline <YYYY-MM-DD|none>] [--priority <level>]` or `update (interactive mode)`

Mark or unmark a task: `mark <projectIndex> <taskIndex>` / `unmark <projectIndex> <taskIndex>` or `mark/unmark (interactive mode)`

Delete items: `delete-project <projectIndex> --confirm` or `delete-task <projectIndex> <taskIndex>` or `delete (interactive mode)`

Sort tasks across projects: `sort-tasks <--deadline|--priority> <ascending|descending>` or `sort (interactive mode)`

Filter tasks across projects: `filter-tasks --priority <value>` or `filter (interactive mode)`

Get project status: `status <projectIndex>` or `status --all` or `status (interactive mode)`

Export tasks: `export-tasks <filename>.txt [projectIndex] [filter-tasks --priority <value>] [sort-tasks <--deadline|--priority> <order>]` or `export (interactive mode)`

Get help and exit: `help` / `bye`