1# Pin Command
2
3Pin a route to a specific image tag.
4
5## gordon pin
6
7### Synopsis
8
9```bash
10gordon pin <domain> [options]
11gordon pin list <domain>
12```
13
14### Arguments
15
16| Argument | Description |
17|----------|-------------|
18| `<domain>` | The route domain to pin |
19
20### Options
21
22| Option | Description |
23|--------|-------------|
24| `--tag` | Target tag (skips interactive selection) |
25| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
26| `--token` | Authentication token for remote |
27| `--json` | Output as JSON (for `pin list`) |
28
29### Description
30
31`gordon pin` deploys a selected image tag for the given route. Tags are
32listed from the Gordon registry, with semver tags sorted in descending
33order first, followed by non-semver tags.
34
35Use cases:
36- **Rollback** — revert to a previous stable version
37- **Forward** — advance to a newer version
38- **Lock** — pin to a specific version instead of following `latest`
39- **Test** — switch to an experimental tag
40
41`gordon pin list <domain>` lists available tags without deploying and
42marks the current tag.
43
44If the selected tag matches the current running tag, no action is taken.
45
46### Examples
47
48```bash
49# Interactive selection
50gordon pin myapp.example.com
51
52# Pin to a specific tag
53gordon pin myapp.example.com --tag v1.2.0
54
55# List available tags for a domain
56gordon pin list myapp.example.com
57
58# List available tags as JSON
59gordon pin list myapp.example.com --json
60```
61
62### Notes
63
64- Local by default; remote mode optional. See [CLI Overview](./index.md) for targeting options.
65- Tags are read from the Gordon registry configured on the server.
66
67## Related
68
69- [CLI Overview](./index.md)
70- [Push Command](./push.md)
71- [Routes Command](./routes.md)
72- [Deployment Rollback Strategies](../deployment/rollback.md)