# What does DCli do?

DCli has a singular focus:

{% hint style="info" %}
make it easy to build command line apps using the Dart programming language.
{% endhint %}

DCli has the following aims:

* make building CLI apps as easy as walking.
* fully utilise the expressiveness of Dart.
* works seamlessly with the core Dart libraries.
* provide a cross platform API for Windows, OSx and Linux.
* call any CLI app.
* make debugging CLI apps easy.
* generate error messages that make it easy to resolve problems.
* provide quality documentation and examples.

## DCli's API covers a number of areas:

## User input

Asking the user to input data into a CLI application should be simple. DCli provides a number of functions to facilitate user input.

* ask
* confirm
* menu

```dart
import 'package:dcli/dcli.dart';
void main(){
   var username = ask('Username:', validator: Ask.required);
   if (confirm('Are you over 18')) {
       print(orange('Welcome to the club'));
   }
   
   var selected = menu('Select your poison', options: ['beer', 'wine', 'spirits']
      defaultOption: 'beer');
   print(green('You choice was: $selected'));
}
```

{% hint style="info" %}
**DCli provides an extensive API designed specifically for building command-line apps.**
{% endhint %}

## Displaying information

Out-of-the-box Dart provides the basic 'print' statement which DCli extends to provide common features.

* print
* printerr - prints to stderr.
* colour coding
* cursor management
* clear screen/clear line

```dart
print(orange("I'm an important message"));
printerr(red('Oops, something went wrong here'));
```

## Manage files and directories

A fundamental task of most CLI applications is the management of files and directories. DCli provides a large set of tools for file management such as:

* find
* which
* copy
* copyTree
* move
* moveTree
* delete
* deleteDir
* touch
* exists
* isWritable/isReadable/isExecutable
* isFile
* isLink
* isDirectory
* lastModified

{% hint style="info" %}
Dart has a large ecosystem of packages that you can use to extend the DCli such as the excellent [paths](https://pub.dev/packages/path) package that lets you easily manipulate file paths.
{% endhint %}

```dart
import 'package:dcli/dcli.dart';
void main() {
    if (!exists('/keep')) {
        createDir('/keep');
    }
    
    var images = find('*.png', root: '/images');
    for (var image in images) {
        if (image.startsWith('nsfw')) {
            copy(image, '/keep');
        }
    }
}
```

## Read/Write files

You are often going to need to read/write and modify text and binary files.

* read
* write
* truncate
* append
* replace
* tail
* cat

{% hint style="info" %}
You still have full access to the full set of Dart APIs
{% endhint %}

```dart
//  write lines to myfile.ini
var settings = 'myfile.ini';
settings.write('[section1]');
settings.append('color=red');
settings.append('color=blue');

// fix the spelling in myfile.ini
replace(settings, 'color', 'colour');
```

## Call command line apps

A core feature of DCli is the ability to call other CLI apps and process their output.

* run
* start
* toList
* forEach
* firstLine
* lastLine
* \| (pipe)
* stream

Run mysql with all output being displayed to the console.

```dart
var user = ask('username');
var password = ask('password', hidden:true);
'mysql -u $user --password=$password customerdb -e "select 1"'.run;
```

Run a mysql command and store the results in a list (users).

```dart
var users = 'mysql customerdb -e "select fname, sname from user"'
    .toList(skipLines: 1);
/// now parse each user and print their name
for (var user in users) {
    var parts = user.split(',');
    print('Firstname: ${parts[0]} Surname: ${parts[1]});
}
/// Run grep and print each line that it finds
'grep error /var/lib/syslog'.forEach((line) => print(line));
```

## Explore you environment

DCli makes it easy to explore your environment with direct manipulation of environment variables.

```dart
var user = env['USER'];
env['JAVA_HOME'] = '/usr/lib/java';
```

PATH management tools:

```dart
Env().appendToPath('/home/me/bin');
Env().addToPATHIfAbsent('/home/me/bin');
Env().removeFromPATH('/home/me/bin');
```

And the ability to explore the Dart environment.

```dart
/// Get details of the current dart script that is running.
DartScript.current;
DartSdk().pathToDartExe;
PubCache().pathTo
```

{% hint style="info" %}
You can explore the complete API [here](https://pub.dev/documentation/dcli/latest/).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dcli.onepub.dev/what-does-dcli-do.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.