Skip to content

Commit 24c67e2

Browse files
CodeMan99CodeMan99
committed
Provide more example usage.
1 parent 0d77a17 commit 24c67e2

File tree

1 file changed

+132
-7
lines changed

1 file changed

+132
-7
lines changed

‎README.md‎

Lines changed: 132 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,39 +7,164 @@ Create and manage devcontainer configuration.
77

88
## Usage
99

10-
The to see help on input flags.
10+
Use `--help` to see help on input flags.
1111

1212
```shell
1313
$ tyedev --help
14+
Create and manage devcontainer configuration
15+
16+
Usage: tyedev [OPTIONS] [COMMAND]
17+
18+
Commands:
19+
completions Generate shell auto-complete configuration
20+
init Create new devcontainer
21+
inspect Display details of a specific feature, template, or collection
22+
list Overview of collections
23+
search Text search the `id`, `keywords`, and `description` fields of templates or features
24+
help Print this message or the help of the given subcommand(s)
25+
26+
Options:
27+
-p, --pull-index Pull the index of features & templates
28+
-v, --verbose... More output per occurrence
29+
-q, --quiet... Less output per occurrence
30+
-h, --help Print help
31+
-V, --version Print version
1432
```
1533

1634
All of the commands depend on a local copy of the _generated_ [collection index](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml).
1735

1836
```shell
19-
$ tyedev --pull-index
37+
$ tyedev --pull-index --verbose
38+
[2023-11-23T15:28:33.056Z INFO tyedev] Saved to /home/vscode/.local/share/tyedev/devcontainer-index.json
2039
```
2140

2241
### Features
2342

24-
...
43+
The `tyedev` application is organized into sub-commands.
2544

2645
#### tyedev init
2746

28-
Use to start a new project. Provide no arguments for the default interactive experience. Use `--help` to learn what can be provided as arguments.
47+
Use to start a new project. Provide no arguments for the default interactive experience.
48+
49+
```shell
50+
$ tyedev init --help
51+
Create new devcontainer
52+
53+
Usage: tyedev init [OPTIONS]
54+
55+
Options:
56+
-z, --non-interactive Avoid interactive prompts
57+
-s, --attempt-single-file Write to ".devcontainer.json" when using an `image` type template
58+
-v, --verbose... More output per occurrence
59+
-q, --quiet... Less output per occurrence
60+
-r, --remove-comments Strip comments from the generated devcontainer.json
61+
-t, --template-id <OCI_REF> Reference to a Template in a supported OCI registry
62+
-f, --include-features <OCI_REF> Add the given features, may specify more than once
63+
--include-deprecated Include deprecated results when searching
64+
-w, --workspace-folder <DIRECTORY> Target workspace for the devcontainer configuration
65+
-h, --help Print help
66+
```
2967

3068
Note that `--remove-comments` is not yet actually supported. A better `jsonc` library would be helpful. May need to write my own.
3169

3270
#### tyedev inspect
3371

34-
Describe all details of a specific template or feature. The `id` is a required argument. Use as an aid when editing an existing `devcontainer.json`.
72+
Describe all details of a specific template or feature. Use as an aid when editing an existing `devcontainer.json`.
73+
74+
```shell
75+
$ tyedev inspect --help
76+
Display details of a specific feature, template, or collection
77+
78+
Usage: tyedev inspect [OPTIONS] <OCI_REF>
79+
80+
Arguments:
81+
<OCI_REF> The `id` to inspect
82+
83+
Options:
84+
-d, --display-as <FORMAT> Format for displaying the configuration [default: table] [possible values: table, json,
85+
none]
86+
--install-sh Read the `install.sh` script of a given feature
87+
-v, --verbose... More output per occurrence
88+
-q, --quiet... Less output per occurrence
89+
--show-files List the filenames of a given feature or template
90+
-h, --help Print help
91+
```
92+
93+
The `--show-files` option exists to assist authors with debugging a missing file problem.
94+
95+
The `--install-sh` option exists for debugging container creation failures.
3596

3697
#### tyedev list
3798

38-
List collections overview. With `--collection-id` option display all features or templates for the given collection.
99+
List collections overview. Akin to [containers.dev/collections](https://containers.dev/collections).
100+
101+
```shell
102+
$ tyedev list --help
103+
Overview of collections
104+
105+
Usage: tyedev list [OPTIONS]
106+
107+
Options:
108+
-C, --collection-id <OCI_REF> Display a given collection, including features and templates
109+
-v, --verbose... More output per occurrence
110+
-q, --quiet... Less output per occurrence
111+
-h, --help Print help
112+
```
113+
114+
With `--collection-id` option display all features or templates for the given collection.
115+
116+
```shell
117+
$ tyedev list -q -C ghcr.io/codeman99/features
118+
Name: Features by CodeMan99
119+
Maintainer: Cody Taylor
120+
Contact: https://github.com/CodeMan99/features/issues
121+
Repository: https://github.com/CodeMan99/features
122+
OCI Reference: ghcr.io/codeman99/features
123+
┌───┬─────────┬────────────────┬──────────────┬───────────────────────────────────────────────────────────────────────┐
124+
│ │ Type │ OCI Reference │ Name │ Description │
125+
├───┼─────────┼────────────────┼──────────────┼───────────────────────────────────────────────────────────────────────┤
126+
│ 1 │ feature │ ~/circleci-cli │ CircleCI CLI │ Install the CircleCI CLI. Also installs the CircleCI extension for v+ │
127+
│ 2 │ feature │ ~/exercism-cli │ Exercism CLI │ Install the exercism-cli. │
128+
└───┴─────────┴────────────────┴──────────────┴───────────────────────────────────────────────────────────────────────┘
129+
```
39130

40131
#### tyedev search
41132

42-
Find a template or feature from the official [collections](https://containers.dev/collections).
133+
Find a [template](https://containers.dev/templates) or [feature](https://containers.dev/features).
134+
135+
```shell
136+
$ tyedev search --help
137+
Text search the `id`, `keywords`, and `description` fields of templates or features
138+
139+
Usage: tyedev search [OPTIONS] <VALUE>
140+
141+
Arguments:
142+
<VALUE> The keyword(s) to match
143+
144+
Options:
145+
-c, --collection <COLLECTION> Match which section of the index [default: templates] [possible values: templates,
146+
features]
147+
-d, --display-as <FORMAT> Format for displaying the results [default: table] [possible values: table, json]
148+
-v, --verbose... More output per occurrence
149+
-f, --fields <FIELD> Match only within the given fields [possible values: id, name, description, keywords]
150+
-q, --quiet... Less output per occurrence
151+
--include-deprecated Display deprecated results
152+
-h, --help Print help
153+
```
154+
155+
Example: Find a _feature_ with `circleci` in the _name_ field only, and output as _json_.
156+
157+
```shell
158+
$ tyedev search --quiet -d json -f id -c features circleci-cli | jq '.[1]'
159+
{
160+
"collection": "Features",
161+
"id": "ghcr.io/codeman99/features/circleci-cli",
162+
"version": "1.2.0",
163+
"name": "CircleCI CLI",
164+
"description": "Install the CircleCI CLI. Also installs the CircleCI extension for vscode.",
165+
"keywords": null
166+
}
167+
```
43168

44169
### Non-Features
45170

0 commit comments

Comments
 (0)