> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ankra targets

> Manage host deploy targets

## ankra targets

Manage host deploy targets: machines outside Kubernetes that run the
ankra-host-agent and receive releases from 'kind: deploy' pipeline stages.

A host joins an environment with a single-use join token:

```bash theme={null}
# as an organisation admin
ankra targets join-token create --environment production -o json

# as root on the host
ankra targets register --environment production --name web-1 --token-stdin
```

The agent only ever connects outbound over HTTPS; the host needs no inbound
port.

## ankra targets get

Show a host deploy target

```bash theme={null}
ankra targets get <name|id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--environment` | | Environment to look the name up in, when several environments use it |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra targets join-token

Mint join tokens that let a host register into an environment

## ankra targets join-token create

Mint a single-use join token a host registers into the environment with.
The environment is created when it does not exist yet.

The token is shown exactly once: the platform keeps only its hash. Without -o
it is the only thing written to stdout (the expiry and the next step go to
stderr), so it can be piped straight into 'ankra targets register
`--token-stdin`' on the host.

```bash theme={null}
ankra targets join-token create [flags]
```

**Examples**

```bash theme={null}
ankra targets join-token create --environment production
  ankra targets join-token create --environment production --ttl 4h -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--environment` | | Environment the host registers into (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ttl` | `1h0m0s` | How long the token stays valid (at most 24h) |

## ankra targets list

List host deploy targets

```bash theme={null}
ankra targets list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--environment` | | Only list targets in this environment |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra targets register

Register this machine as a host deploy target and start its agent. Run it
as root on the host itself, with a join token from 'ankra targets join-token
create' on stdin.

The command:

1. downloads ankra-host-agent for this machine's OS and architecture and its
   systemd unit from the agent release, and refuses them unless their
   SHA-256 matches the release's SHA256SUMS;
2. installs the binary as /usr/local/bin/ankra-host-agent;
3. runs 'ankra-host-agent register', passing the join token on stdin - the
   agent does the registration and stores its own identity token;
4. installs and starts ankra-host-agent.service.

The CLI never sends the join token anywhere itself and needs no 'ankra login'
on the host. `--no-install` prints these steps without doing any of them.

The agent reaches the platform at `--base-url` (or the configured base URL),
over outbound HTTPS only.

```bash theme={null}
ankra targets register [flags]
```

**Examples**

```bash theme={null}
ankra targets join-token create --environment production | \
    ssh root@web-1 ankra targets register --environment production --name web-1 --label role=web --token-stdin

  ankra targets register --environment production --name web-1 --token-stdin --no-install
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--agent-version` | `latest` | Agent release to install, e.g. v2.1.40 |
| `--environment` | | Environment to register into (required) |
| `--label` | `[]` | Label as key=value; repeat for more (deploy stages select targets by label) |
| `--name` | | Name of this host target, unique in the environment (required) |
| `--no-install` | `false` | Print what would be downloaded, run and installed, and do nothing |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--release-url` | | Base URL of the agent releases (default [https://github.com/ankraio/ankra-host-agent/releases](https://github.com/ankraio/ankra-host-agent/releases), or \$ANKRA\_HOST\_AGENT\_RELEASE\_URL) |
| `--token-stdin` | `false` | Read the join token from stdin (required; the token is never taken as a flag) |

## ankra targets revoke

Revoke a host deploy target. Its identity token and every session stop
working at once and it receives no further deploy jobs; the releases already
on the host keep running. A revoked host registers again only with a new
join token.

```bash theme={null}
ankra targets revoke <name|id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--environment` | | Environment to look the name up in, when several environments use it |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Revoke without asking for confirmation |