Extensions #

Extensions are a new feature in tdl. They are still in the experimental stage, and the CLI may change in future versions.
If you encounter any problems or have any suggestions, please open an issue on GitHub.

Overview #

tdl extensions are add-on tools that integrate seamlessly with tdl. They provide a way to extend the core feature set of tdl, but without requiring every new feature to be added to the core.

tdl extensions have the following features:

They can be added and removed without impacting the core tdl tool.
They integrate with tdl, and will show up in tdl help and other places.

tdl extensions live in ~/.tdl/extensions, which is controlled by tdl extension commands.

To get started with extensions, you can use the following commands:

tdl extension install iyear/tdl-whoami

tdl whoami

You can see the output of the tdl-whoami extension. Refer to the tdl-whoami for details.

You are XXXXX. ID: XXXXXXXX

Finding extensions #

You can find extensions by browsing repositories with the tdl-extension topic.

Installing extensions #

To install an extension, use the extension install subcommand.

There are two types of extensions:

GitHub : Extensions hosted on GitHub repositories.
```
tdl extension install <owner>/<repo>
```
To install an extension from a private repository, you must set up a GitHub personal access token(with Contents read permission) in your environment with the GITHUB_TOKEN variable.
```
export GITHUB_TOKEN=YOUR_TOKEN
tdl extension install <owner>/<private-repo>
```
Local : Extensions stored on your local machine.
```
tdl extension install /path/to/extension
```

To install an extension even if it exists, use the --force flag:

tdl extension install --force EXTENSION

To install multiple extensions at once, use the following command:

tdl extension install <owner>/<repo1> /path/to/extension2 ...

To only print information without actually installing the extension, use the --dry-run flag:

tdl extension install --dry-run EXTENSION

If you already have an extension by the same name installed, the command will fail. For example, if you have installed foo/tdl-whoami, you must uninstall it before installing bar/tdl-whoami.

Running extensions #

When you have installed an extension, you run the extension as you would run a native tdl command, using tdl EXTENSION-NAME. The EXTENSION-NAME is the name of the repository that contains the extension, minus the tdl- prefix.

For example, if you installed the extension from the iyear/tdl-whoami repository, you would run the extension with the following command.

tdl whoami

Global config flags are still available when running an extension. For example, you can run the following command to specify namespace and proxy when running the tdl-whoami extension.

tdl -n foo --proxy socks5://localhost:1080 whoami

Flags specific to an extension can also be used. For example, you can run the following command to enable verbose mode when running the tdl-whoami extension.

Remember to write global flags before extension subcommands and write extension flags after extension subcommands:
tdl <global-config-flags> <extension-name> <extension-flags>

tdl -n foo whoami -v

You can usually find specific information about how to use an extension in the README of the repository that contains the extension.

Viewing installed extensions #

To view all installed extensions, use the extension list subcommand. This command will list all installed extensions, along with their authors and versions.

tdl extension list

Updating extensions #

To update an extension, use the extension upgrade subcommand. Replace the EXTENSION parameters with the name of extensions.

tdl extension upgrade EXTENSION1 EXTENSION2 ...

To update all installed extensions, keep the EXTENSION parameter empty.

tdl extension upgrade

To upgrade an extension from a GitHub private repository, you must set up a GitHub personal access token(with Contents read permission) in your environment with the GITHUB_TOKEN variable.

export GITHUB_TOKEN=YOUR_TOKEN
tdl extension upgrade EXTENSION

To only print information without actually upgrading the extension, use the --dry-run flag:

tdl extension upgrade --dry-run EXTENSION

Uninstalling extensions #

To uninstall an extension, use the extension remove subcommand. Replace the EXTENSION parameters with the name of extensions.

tdl extension remove EXTENSION1 EXTENSION2 ...

To only print information without actually uninstalling the extension, use the --dry-run flag:

tdl extension remove --dry-run EXTENSION

Developing extensions #

Please refer to the tdl-extension-template repository for instructions on how to create, build, and publish extensions for tdl.