orcli/src/bashly.yml

name: orcli
help: OpenRefine command-line interface written in Bash
version: 0.1.0
footer: https://github.com/opencultureconsulting/orcli

dependencies:
  - curl
  - jq

environment_variables:
  - name: OPENREFINE_URL
    help: URL to OpenRefine server
    default: "http://localhost:3333"

examples:
  - orcli import csv "https://git.io/fj5hF" --projectName "duplicates"
  - orcli list
  - orcli info "duplicates"
  - orcli transform "duplicates" "https://git.io/fj5ju"
  - orcli export tsv "duplicates"
  - orcli export tsv "duplicates" --output "duplicates.tsv"
  - orcli run --interactive
  - |-
    orcli run << EOF
      orcli import csv "https://git.io/fj5hF" --projectName "duplicates"
      orcli transform "duplicates" "https://git.io/fj5ju"
      orcli export tsv "duplicates"
    EOF

commands:
  - name: completions
    help: |-
      Generate bash completions
      Usage: eval "\$(orcli completions)"

  - name: import
    help: commands to create OpenRefine projects from files or URLs

    commands:
      - name: csv
        help: import character-separated values (CSV)
        args:
          - name: file
            help: Path to one or more files or URLs. When FILE is -, read standard input.
            default: "-"
            repeatable: true
        flags:
          - long: --separator
            help: character(s) that separates columns
            arg: separator
            default: ","
          - long: --encoding
            help: set character encoding
            arg: encoding
          - long: --trimStrings
            help: trim leading & trailing whitespace from strings
          - long: --projectName
            arg: projectName
            help: set a name for the OpenRefine project
          - long: --quiet
            short: -q
            help: suppress log output, print errors only
        examples:
          - orcli import csv "file"
          - orcli import csv "file1" "file2"
          - cat "file" | orcli import csv
          - orcli import csv "https://git.io/fj5hF"
          - |-
            orcli import csv "file" \\\\
              --separator ";" \\\\
              --encoding "ISO-8859-1" \\\\
              --trimStrings \\\\
              --projectName "duplicates"

      - name: tsv
        help: import tab-separated values (TSV)
        args:
          - name: file
            help: Path to one or more files or URLs. When FILE is -, read standard input.
            default: "-"
            repeatable: true
        flags:
          - long: --encoding
            help: set character encoding
            arg: encoding
          - long: --trimStrings
            help: trim leading & trailing whitespace from strings
          - long: --projectName
            arg: projectName
            help: set a name for the OpenRefine project
          - long: --quiet
            short: -q
            help: suppress log output, print errors only
        examples:
          - orcli import tsv "file"
          - orcli import tsv "file1" "file2"
          - cat "file" | orcli import tsv
          - orcli import tsv "https://git.io/fj5hF"
          - |-
            orcli import tsv "file" \\\\
              --separator ";" \\\\
              --encoding "ISO-8859-1" \\\\
              --trimStrings \\\\
              --projectName "duplicates"

  - name: list
    help: list projects on OpenRefine server

  - name: info
    help: show OpenRefine project's metadata
    args:
      - name: project
        help: project name or id
        required: true
    examples:
      - orcli info "duplicates"
      - orcli info 1234567890123

  - name: test
    help: run functional tests on tmp OpenRefine workspace

  - name: transform
    help: apply undo/redo JSON file(s) to an OpenRefine project
    args:
      - name: project
        help: project name or id
        required: true
      - name: file
        help: Path to one or more files or URLs containing OpenRefine's undo/redo operation history in JSON format. When FILE is -, read standard input.
        default: "-"
        repeatable: true
    flags:  
      - long: --quiet
        short: -q
        help: suppress log output, print errors only
    examples:
      - orcli transform "duplicates" "history.json"
      - cat "history.json" | orcli transform "duplicates"
      - orcli transform "duplicates" "https://git.io/fj5ju"
      - orcli transform 1234567890123 "history.json"

  - name: export
    help: commands to export data from OpenRefine projects to files

    commands:
      - name: tsv
        help: export tab-separated values (TSV)
        args:
          - name: project
            help: project name or id
            required: true
        flags:
          - long: --output
            help: Write to file instead of stdout
            arg: file
          - long: --encoding
            help: set character encoding
            arg: encoding
            default: "UTF-8"
          - long: --quiet
            short: -q
            help: suppress log output, print errors only
        examples:
          - orcli export tsv "duplicates"
          - orcli export tsv "duplicates" --output "duplicates.tsv"

  - name: run
    help: run tmp OpenRefine workspace and execute shell script(s)
    args:
      - name: file
        help: Path to one or more files. When FILE is -, read standard input.
        default: "-"
        repeatable: true
    flags:
      - long: --memory
        help: maximum RAM for OpenRefine java heap space
        arg: ram
        default: "2048M"
      - long: --port
        help: PORT on which OpenRefine should listen
        arg: port
        default: "3333"
      - long: --interactive
        help: do not exit on error and keep bash shell open
      - long: --quiet
        short: -q
        help: suppress log output, print errors only
    examples:
      - orcli run --interactive
      - |-
        orcli run << EOF
          orcli import csv "https://git.io/fj5hF" --projectName "duplicates"
          orcli transform "duplicates" "https://git.io/fj5ju"
          orcli export tsv "duplicates"
        EOF
      - |-
        orcli run --memory "2000M" --port "3334" << EOF
          orcli import csv "https://git.io/fj5hF" --projectName "duplicates" &
          orcli import csv "https://git.io/fj5hF" --projectName "copy" &
          wait
          echo "finished import"
          orcli export csv "duplicates" --output duplicates.csv &
          orcli export tsv "duplicates" --output duplicates.tsv &
          wait
          wc duplicates*
        EOF
      - |-
        orcli run --interactive "file1.sh" "file2.sh" - << EOF
          echo "finished in \$SECONDS seconds"
        EOF