javicle/docs/running.md

# Running JVCL

## The `jvcl` Script
The `bin/jvcl` script is the primary way to transform video assets with JVCL.

## Operation-specific scripts
There are other scripts in [`bin`](../bin) that perform a single operation using
command-line arguments. If you need to do a quick operation and don't want to write
a JVCL spec, use one of these tools.

For example, to extract the first 5 seconds of a video:
```shell script
jtrim /tmp/input-file.mp4 /tmp/output-5s.mp4 0 5
```

All commands accept a `-h` / `--help` option, use this to print usage information:
```shell script
jscale -h
```

## JVCL Spec Files
A JVCL spec is just a regular JSON file that happens to contain a single JSON object,
whose properties are `assets` and `operations`.

When you run `jvcl` on a spec file, it will load the `assets`, then perform the `operations` in order.

Learn more about [Assets and Operations](concepts.md)

Unlike most JSON, comments *are* allowed in JVCL spec files:
* A line comment starts with `//` and continue to the end of the line
* A multi-line block starts with `/*` and ends with `*/`

## Writing a JVCL Spec
The easiest way to write a spec is to copy one of the
[test specs](../src/test/resources/tests) and edit it.

There examples for every JVCL operation.

## Executing a JVCL Spec
To execute a spec stored in the file `my-spec.json`, you would run:
```shell script
jvcl my-spec.jvcl
```
or use stdin:
```shell script
cat my-spec.jvcl | jvcl
```

## Command Line Options

#### Scratch Directory
Output assets will be placed in the scratch directory, unless otherwise specified
in the spec file. By default, JVCL will create a new temporary directory to use as the scratch
directory. You can set the scratch directory explicitly using the `-t` or `--temp-dir` option:
```shell script
jvcl -t /some/tempdir my-spec.json
```

When using the other tools in `bin`, you can set the scratch directory via the
`JVCL_SCRATCH_DIR` environment variable. If the `JVCL_SCRATCH_DIR` references a
directory that does not exist, it will be created.

#### Dry Run
Use the `-n` or `--no-exec` option to print out the commands that would have been run,
but do not actually run anything.
```shell script
jvcl -n my-spec.json         # will not run any ffmpeg commands
```
Note that this breaks JVCL operations that require information from any assets created by
previous operations: since the command did not actually run, the intermediate asset was
never created.

When using the other tools in `bin`, you can set the "no exec" flag via the
`JVCL_NO_EXEC` environment variable. If the `JVCL_NO_EXEC` is non-empty, then
the script will pass the `-n` flag when it calls `jvcl` and commands will
be printed out instead of actually being run.

#### Help
To view a list of all `jvcl` command-line options, run `jvcl -h` or `jvcl --help`

# What's Next?
Learn about [Assets and Operations](concepts.md), the core concepts of JVCL.