jirac/readme.md

# Jirac

A CLI for creating and managing Jira tickets directly from your terminal.

## Features

- Create Jira tickets from markdown files or using your preferred editor
- List tickets assigned to specific users
- Simple configuration using TOML
- Interactive ticket creation with templates
- Execute JQL

## Installation

### from crates.io

```
cargo install jirac 
```

## Usage

```
Usage: jirac <COMMAND>

Commands:
  create  Create an issue
  list    Find issues currently assigned to you
  search  Search for issues
  init    Set up the configuration
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
```

### Creating a ticket

```
Create a ticket

Usage: jirac create [OPTIONS] [MARKDOWN_FILE]

Arguments:
  [MARKDOWN_FILE]  A markdown file

Options:
      --project <PROJECT>  The project key in which to create the ticket
      --open               Open the new ticket in a browser
  -h, --help               Print help
```

*Using your favourite editor*

```sh
jirac create
```

*From a markdown file*

```sh
jirac create ticket.md
```

*Specify a project*

```sh
jirac create --project KEY
```

### Listing tickets

```
Find tickets currently assigned to you

Usage: jirac list [OPTIONS]

Options:
      --json  Print json rather than pretty print
  -h, --help  Print help
```

### Search for tickets

```
Search for issues

Usage: jirac search [OPTIONS] <JQL>

Arguments:
  <JQL>  A JQL string

Options:
      --json  Print JSON rather than pretty print
  -h, --help  Print help
```

Use [JQL](https://support.atlassian.com/jira-software-cloud/docs/use-advanced-search-with-jira-query-language-jql/) to search for Issues.

*Find all in-progress tickets in a project*

```
jirac search 'project = KEY AND status = "In Progress" ORDER BY created DESC'
```

## Configuration

Get the following information:

* Jira instance URL
* You email
* [An API key](https://id.atlassian.com/manage-profile/security/api-tokens)

Then run the `jirac init` command

```
Setup the configuration

Usage: jirac init --url <URL> --email <EMAIL> --token <TOKEN>

Options:
      --url <URL>      Jira instance URL
      --email <EMAIL>  User email
      --token <TOKEN>  User Token
  -h, --help           Print help
```

The config file is stored at:

| OS      | Location                                                       |
|---------|----------------------------------------------------------------| 
| Windows | `~/.config/jirac/config.toml`                                  |
| MacOS   | `~/Library/Application Support/com.runebaas.jirac/config.toml` |
| Linux   | `%APPDATA%\runebaas\jirac\config\config.toml`                  |