CLI reference

For feature teams and platform teams. This page lists every command of the joomiz CLI, its options, the exit codes and the variables that the CLI reads. Use joomiz <command> --help to see the same options in your terminal.

Global options

Every command accepts these options.

Option	Meaning
`-h`, `--help`	Show the help of the command and exit.
`-V`, `--version`	Print the version and exit.

Commands

Command	What it does	Talks to the control plane
`init`	Writes a new `joomiz.yaml` with an application and its owner.	No
`register`	Sends a `joomiz.yaml` to the control plane for the first time.	Yes
`validate`	Checks a `joomiz.yaml` and changes nothing.	Yes
`plan`	Shows what an apply would change in one environment, and changes nothing.	Yes
`apply`	Makes the changes of a plan in one environment.	Yes
`runs`	Lists your plan and apply runs.	Yes
`runs show`	Prints one run.	Yes
`runs watch`	Follows a run until it is final.	Yes
`runs abandon`	Releases the apply lock of a run. For operators.	Yes
`audit`	Prints the audit trail that you may read.	Yes
`login`	Signs you in to the identity provider and saves the sign-in.	No
`tooling add`	Adds a tool entry to a `joomiz.yaml`.	No

Options of the commands that talk to the control plane

register, validate, plan, apply, runs, runs show, runs watch, runs abandon and audit share these options.

Option	Default	Meaning
`--server=<url>`	The variable `JOOMIZ_SERVER_URL`, then an address for local development	The address of the control plane. Use the `https://` address that your platform team gives you.
`--token`	The variable `JOOMIZ_TOKEN`, then the sign-in of `joomiz login`	The token to send. A token that you give starts no sign-in. Use `joomiz login` or `JOOMIZ_TOKEN` instead: a value on the command line stays in the shell history.

The commands that read a file also take -f, --file=<path>. The default is joomiz.yaml in the current folder.

init

Writes a new joomiz.yaml. It never overwrites a file, and it does not contact the control plane. In a terminal, it asks for the values that you leave out. Without a terminal, it stops and names them.

Option	Required	Default	Meaning
`--name=<kebab-case>`	Yes		The name of the application.
`--repository=<https-url>`	Yes		The address of your code.
`--golden-path=<value>`	Yes		The golden path of the service.
`--owner-id=<slug>`	Yes		The ID of the owner team.
`--owner-name=<text>`	Yes		The name of the owner team.
`--description=<text>`	No		What the service does.
`--id=<uuid>`	No	A new UUID	The ID of the application.
`-o`, `--output=<path>`	No	`joomiz.yaml`	Where to write the file.

Deploy your first service shows the command with its output.

register

Sends the file to the control plane. It checks the structure of the whole file against the published schema and the size limits. It stores the application, its owner and the lists artifacts and tooling. It does not check the references between entries, the compatibility rules or duplicate ids. validate and plan check those.

Options: -f, --server, --token.

validate

Checks the whole file: the schema, the application block, tooling, every environment against the catalogs, and the references. The application must be registered. It changes nothing.

Option	Meaning
`--json`	Print the answer of the control plane as JSON instead of a report.

Also: -f, --server, --token. Check your file shows the output.

plan

Shows what an apply would change in one environment. It changes nothing.

Option	Required	Meaning
`--environment=<name>`	Yes	The environment to plan.
`--json`	No	Print the answer of the control plane as it is, instead of a report.
`--strict`	No	Exit with `5` when the drift check is incomplete. Without it, such a plan exits with `0` and ends with a line that starts with `incomplete:`.

Also: -f, --server, --token. Preview a change shows the output.

apply

Makes the changes of a plan in one environment. The file must be the same as the file that you planned. Only one apply can run at a time for an application and an environment. An apply of a plan that is out of date is refused.

Option	Required	Meaning
`--environment=<name>`	Yes	The environment to apply.
`--json`	No	Print the answer of the control plane as it is, instead of a report.

Also: -f, --server, --token. Make a change shows the output.

runs

Lists the runs that you may see, newest first.

Option	Default	Meaning
`--application=<id>`		Only runs of this application. Give its ID.
`--environment=<name>`		Only runs in this environment.
`--kind=<kind>`		Only runs of one action: `plan` or `apply`.
`--status=<status>`		Only runs with one status: `running`, `accepted`, `succeeded`, `failed`, `partially_applied`, `refused` or `abandoned`.
`--limit=<n>`	20	The largest number of runs to print, from 1 to 1000.

Also: --server, --token. A value that is not allowed for --status gives exit code 2.

runs show

joomiz runs show <id> prints one run, with one line for each type of resource. The exit code is 0 for a run that succeeded and 4 for a run that is not final. It is 1 for a run that ended without success.

runs watch

joomiz runs watch <id> prints the events of a run as they arrive, and it stops when the run is final. It waits for an accepted run until its provisioners finish. Press Ctrl+C to stop watching.

runs abandon

joomiz runs abandon <id> releases the apply lock of a run that is running or accepted. Only a person with the role operator can use it. It does not stop work that is already running.

Read your runs shows the output of the three commands.

audit

Prints the audit trail that you may read, newest first. It shows who registered or changed a provisioner, who registered an application, who applied, and who released a run.

Option	Default	Meaning
`--action=<name>`		Only this action, for example `apply.requested`.
`--actor=<subject>`		Only events of one user ID. For operators only.
`--application=<id>`		Only events of this application.
`--run=<id>`		Only events of this run.
`--outcome=<outcome>`		Only this outcome: `performed` or `refused`. This documentation says blocked for `refused`.
`--from=<time>`		Only events at or after this time, in ISO 8601 form.
`--to=<time>`		Only events before this time, in ISO 8601 form.
`--limit=<n>`	50	The largest number of events to print, from 1 to 1000.

Also: --server, --token. A person with the role owner:<team> sees the events of the applications of the team.

Signs you in and saves the sign-in for the other commands. It does not open a browser. It prints an address and a code. Sign in and get access shows the steps.

Option	Variable	Meaning
`--authority=<url>`	`JOOMIZ_AUTHORITY`	The address of your identity provider.
`--client-id=<id>`	`JOOMIZ_CLIENT_ID`	The ID of the client of the CLI.
`--scope=<scope>`	`JOOMIZ_SCOPE`	The scopes to ask for, separated by spaces. The default is `openid profile offline_access`. Keep `offline_access`, or the CLI cannot renew the sign-in.

tooling add

Adds one entry to the end of tooling in a file. It creates the section when the file has none. It does not check the tool type. Run validate for that.

Option	Required	Default	Meaning
`--id=<kebab-case>`	Yes		The ID of the entry.
`--type=<kebab-case>`	Yes		The tool type.
`--spec=<key=value>`	No		A setting. Repeat the option for each setting. A repeated key keeps the last value.
`--enabled[=<true\|false>]`	No	`true`	Whether the tool is on.

Also: -f. Declare artifacts and tooling shows the output.

Exit codes

Code	Meaning
`0`	The command worked.
`1`	The control plane found problems in the file or refused the call.
`2`	The command cannot start: a missing or wrong option, an unknown command or no credential.
`3`	The control plane gave no usable answer.
`4`	`runs show` only: the run is not final.
`5`	`plan --strict` only: the drift check is incomplete.

Run results, refusal reasons and exit codes explains each code.

Variables

Variable	Read by	Meaning
`JOOMIZ_SERVER_URL`	The commands that talk to the control plane	The address of the control plane.
`JOOMIZ_TOKEN`	The commands that talk to the control plane	A token to send. It wins over a saved sign-in.
`JOOMIZ_AUTHORITY`	`login`	The address of your identity provider.
`JOOMIZ_CLIENT_ID`	`login`	The ID of the client of the CLI.
`JOOMIZ_SCOPE`	`login`	The scopes to ask for.
`JOOMIZ_CREDENTIALS_FILE`	`login`, and all commands that send a token	The file that holds your saved sign-in. Name a file in a folder of its own, outside your project.

joomiz login saves your sign-in in ~/.joomiz/credentials.json, unless JOOMIZ_CREDENTIALS_FILE names another file. To remove the saved sign-in from this computer, delete the file.