jirac/readme.md

# Jirac

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

## Features

- Create Jira issues from Markdown files or using your preferred editor
- List issues assigned to specific users
- Simple configuration using TOML
- Interactive issue creation with templates
- Search with JQL
- Multiple output methods
- Jira-doc support

## 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
  view    View an issue
  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 ab issue

```
Create an issue

Usage: jirac create [OPTIONS] [MARKDOWN_FILE]

Arguments:
  [MARKDOWN_FILE]  A markdown file

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

*Using your favourite editor*

```sh
jirac create
```

*From a Markdown file*

```sh
jirac create issue.md
```

*Specify a project*

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

### Listing issues

```
Find issues currently assigned to you

Usage: jirac list [OPTIONS]

Options:
  -o, --output <OUTPUT>  Pick an output formatter [default: pretty] [possible values: pretty, json]
  -h, --help             Print help
```

### Search for issues

```
Search for issues

Usage: jirac search [OPTIONS] <JQL>

Arguments:
  <JQL>  A JQL string

Options:
  -o, --output <OUTPUT>  Pick an output formatter [default: pretty] [possible values: pretty, json]
  -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 issues in a project*

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

### View an issue

```
View an issue

Usage: jirac view [OPTIONS] <ISSUE>

Arguments:
  <ISSUE>  An issue key, for example, KEY-123

Options:
  -o, --output <OUTPUT>  Pick an output formatter [default: pretty] [possible values: pretty, json]
  -h, --help             Print help
```

```sh
./target/release/jirac view KEY-123
```

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