# Commands

> Every Command that ships with Tinka, with its flags and output: tinka version and act generate:key.

This guide covers the Commands that ship with Tinka. The Tinka CLI, `tinka`, runs the ones that need no App; `act` runs the ones that work inside an App. List them with `tinka --help` or `act --help`, and add `--help` after a Command's name to see its flags.

```sh
act --help
```

Every Command also answers agents with a single JSON result, described in [Agent mode](agent-mode.md). The JSON examples below show the keys each Command adds.

## tinka version

`tinka version` prints which Tinka you are running, along with the Go toolchain and platform it was built for. Include its output in bug reports so maintainers can reproduce your setup.

```sh
tinka version
```

```text title="Output"
tinka v1.0.0-alpha.1 (go1.27.2, linux/amd64)
```

A binary installed with `go install` reports its release tag. A binary built from a checkout reports a pseudo-version such as `v0.0.0-20261017094113-8b9632f181a3`, ending in `+dirty` when the checkout has uncommitted changes. `tinka --version` prints the same version on its own.

With `--json`, or when an agent runs it, `tinka version` prints a single result:

```text title="Output"
{"command":"version","result":"ok","version":"v1.0.0-alpha.1","go":"go1.27.2","platform":"linux/amd64","duration_ms":0}
```

::::options

:::option{name="version" type="string"}
The Tinka module version this binary was built from.
:::

:::option{name="go" type="string"}
The Go toolchain that built the binary.
:::

:::option{name="platform" type="string"}
The operating system and architecture, such as `linux/amd64`.
:::

::::

## act generate:key

`act generate:key` creates a random `APP_KEY`: 32 bytes from `crypto/rand`, written as 43 URL-safe base64 characters. It writes the key to `.env` and adds `APP_KEY=` with no value to `.env.example`, so the example names the variable without revealing the key. Run it from your App's directory.

```sh
act generate:key
```

```text title="Output"
Wrote APP_KEY to .env and .env.example
```

An existing `APP_KEY` is replaced in place, and every other line of both files stays as it was. The files are found the way `env.Load` finds them, including `ENV_PATH`. `.env.example` is only changed when it exists, and the Command fails when there's no `.env`, because it never creates one.

When `APP_ENV` is `production`, the Command prints the key with a reminder instead of writing it, because production reads no `.env` file:

```text title="Output"
APP_KEY=8fOW8QykADQK8HFBSFcj31kcZmMNiBJP6drrWYwwXho
APP_ENV is production, which reads no .env file: set APP_KEY in your platform's environment
```

Following is the list of flags you can pass to `act generate:key`:

::::options

:::option{name="--show" type="bool"}
Print the key instead of writing it, for example to paste into a platform's settings.
:::

::::

With `--json`, or when an agent runs it, `act generate:key` prints a single result:

```text title="Output"
{"command":"generate:key","result":"ok","files":[".env",".env.example"],"duration_ms":1}
```

::::options

:::option{name="files" type="[]string"}
The files the key was written to. Absent when the key was printed.
:::

:::option{name="key" type="string"}
The key, when it was printed instead of written.
:::

:::option{name="note" type="string"}
Why the key was printed, when `APP_ENV` is `production`.
:::

::::

It fails with one of these error codes:

::::options

:::option{name="no_env_file" type="code"}
There's no `.env` file. Copy `.env.example` to `.env` and run the Command again, or pass `--show`.
:::

:::option{name="invalid_app_env" type="code"}
`APP_ENV` isn't `development`, `test` or `production`, so the Command can't tell where the key belongs.
:::

::::

See also: [The APP_KEY](../configuration.md), [Agent mode](agent-mode.md)