# Etsy Shop CLI
Etspi is a command-line tool that empowers Etsy sellers to manage their shops and listings efficiently. The tool is an interface to the [API](https://developers.etsy.com/documentation)
provided by Etsy and allows viewing and managing the shop and the listings directly with JSON.
## Prerequisites:
- Access to the Etsy API is essential. Review [Etsy Quick Start Guide](https://developers.etsy.com/documentation/tutorials/quickstart) for directions on how to get your personal API key.
- Etspi doesn't provide API key assistance, but it can help with authorization and managing access tokens (explained in the **Authentication** section).
- Familiarity with JMESPath expressions ([link to JMESPath examples](https://jmespath.org/examples.html)) is recommended to filter and transform output data.
## Features:
- **Easy Authentication and Authorization:** Etspi guides you through the process of obtaining and managing API tokens.
- **Automatic Token Management:** Etspi simplifies token maintenance by automatically refreshing access tokens as needed (if configured).
- **Listing Management:** Handle shop listings and variant inventory directly from the command line.
- **Flexible Output Filtering:** Tailor output using JMESPath expressions to retrieve only the data you need.
- **Streamlined Request Formatting:** Transform listing data effortlessly into the appropriate format for draft, listing, or inventory operations.
## Installation:
The recommended installation method is via `pipx`. Refer to the official `pipx` documentation ([link to pipx doc site](https://pipx.pypa.io/stable/)) for installation and usage instructions.
```bash
pipx install etspi-1.0.1
```
If you plan to use Etspi to obtain API tokens, you will also need to have `openssl` installed or some other means to generate certificates suitable for SSL/TLS to secure HTTP server. Alternatively, you can use dedicated tools like Postman to obtain tokens manually. However, Etspi offers a more convenient approach, and you only need to do this once if you persist the tokens. Etspi will automatically use persited refresh token to get a fresh API token when necessary.
## Authentication:
Before you can use the app, you will need to obtain an API key from Etsy. You can find more info and how to request a key on the [developer portal](https://www.etsy.com/developers). Familiarize yourself with the Etsy OAuth 2.0 authentication process ([link to Etsy OAuth 2.0 documentation](https://developers.etsy.com/documentation/essentials/authentication)). Etspi assists with authorization and tokens once you've created an app and acquired an API key.
- Note the Keystring from the App settings. You will need it to start the auth flow.
- In the App settings, you will also need to add a callback URL for the Etspi that will be used in the auth flow.
- By default, it's https://localhost:10443/etspi, but it can be customized using Etspi flags.
- Before you start the auth flow with Etspi, you will also need to create a self-signed SSL certificate/key pair for the tool to use.
- This step is necessary as it is an Etsy requirement that the redirect callback URLs are SSL protected and contain HTTPS prefix.
- You will need OpenSSL installation for this step.
- Run the following from the command prompt/terminal to get the cert/key pair and save them to your home Etspi directory.
- Linux/MacOS:
```bash
openssl req -nodes -x509 -newkey rsa:2048 -keyout ~/.etspi/key.pem -out ~/.etspi/cert.pem -days 365
```
- Windows:
```cmd
openssl req -nodes -x509 -newkey rsa:2048 -keyout %USERPROFILE%\.etspi\key.pem -out %USERPROFILE%\.etspi\cert.pem -days 365
```
- To start the auth flow for all scopes, default redirect URL, and cert/key files from the prior step:
```bash
etspi auth -tF
```
- `-tF` flag saves tokens to the `Auth.env` file. See `etspi auth --help` for more options.
- The Etspi will compose an Auth URL to start the flow.
- Authenticate with Etsy and authorize your app with the assigned keystring for access to the requested scopes.
- Upon authorization completion, Etsy redirects your browser to the defined callback URL, where Etspi is waiting to obtain the tokens.
- The redirect request contains an authorization code from Etsy that is needed to request the tokens.
- If successful in obtaining the tokens, they are saved in `Auth.env` file in the `.etspi/` home folder.
- Most Etspi commands require authorization tokens that can either be pulled from the `Auth.env` file, specified on the command line, or set as environment variables in your shell.
- E.g. `ETSPI_KEY=YOU_ETSY_APP_KEYSTRING` or `ETSPI_TOKEN=YOUR_AUTH_TOKEN`.
- Command line options take precedence over the env variables and variables take precedence over the values stored in the `Auth.env` file.
## Listing:
### listing-get
The most basic use case is to pull listing data by its Id.
```bash
etspi listing-get -i 1800000081
```
Include `-in` flag and option `value` to also include additional data; combine several `values` as needed.
```bash
etspi listing-get -i 1800000081 -in Images -in Shipping
```
Include `-q` or `--query` flag and JMESPath expression to filter and shape the output JSON.
```bash
etspi listing-get -i 1800000081 -q "{ id: listing_id, title: title }"
```
Etsy listing JSON structure from `listing-get` command and `draft` or `listing-update` commands are not symmetrical. If you'd like to create a new draft from existing or update a listing, you will likely want to transform the JSON output into the format ready for `draft` or `listing-update` commands. Use `--format-draft` or `--format-update` flags and combine with `-o` flag to save the result into a file you can modify and later use with each command.
```bash
etspi listing-get -i 1800000081 -in Images --format-draft -o my_listing.json
```
### draft
Create a new draft listing from a JSON data source file. To publish your draft you will need to use the `listing-update` command and set the `state` field to `active`. *Expect Etsy to charge the **listing fee** when you activate the draft.*
```bash
etspi draft -s 10000001 -f my_draft_listing.json
```
### listing-update
Like the `draft` command, you update the listing with the values from a JSON source file specified on the command line.
```bash
etspi listing-update -i 1800000081 -s 10000001 -f my_listing_update.json
```
### listing-delete
This is self-explanatory and will delete a listing by Id. Use `-Y` or `--yes` flat to suppress ***confirmation prompt*** before making the API call to delete the listing!
```bash
etspi listing-delete -i 1800000081 -Y
```
### listing-get-iv
Retrieves the inventory record for a listing by Id.
```bash
etspi listing-get-iv -i 1800000081
```
Include `-q` or `--query` flag and JMESPath expression to filter and shape the output JSON.
```bash
etspi listing-get-iv -i 1800000081 -q "products[?offerings[0].price.amount > `1000`].[product_id, sku]"
```
Use `--format-update` and `-o` flags to transform the output into format suitable for `listing-update-iv` command.
```bash
etspi listing-get-iv -i 1800000081 --format-update -o my_listing_inventory.json
```
### listing-update-iv
Use to update the listing inventory with the values from a JSON source file specified on the command line.
```bash
etspi listing-update-iv -i 1800000081 -f my_listing_update.json
```
## Note on STDOUT redirects
Etspi console output uses `rich` library `print` which will color code and format JSON for more esthetic and readable output. When using Etspi `--out` you get original formatted JSON which is what you want for subsequent commands and API calls. If you have a need to pipe or redirect Etspi output to a different console app or file, you may want this original JSON and not pretty formatted. In that case, consider using `--out` to STDOUT `-` with `-S` and apply your pipe or redirect this way.
```bash
etspi listing-get -i 1800000081 -in Inventory -S -o - | grep "sku"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/sov2000/etspi-cli",
"name": "etspi",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "etsy, api, shop, manager",
"author": "sov2000",
"author_email": "sv28k64@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6c/8a/b3625cea5805451ca7884a85b8b45590bd2f02962d5170e6334a3378781f/etspi-1.0.1.tar.gz",
"platform": null,
"description": "# Etsy Shop CLI\n\nEtspi is a command-line tool that empowers Etsy sellers to manage their shops and listings efficiently. The tool is an interface to the [API](https://developers.etsy.com/documentation) \nprovided by Etsy and allows viewing and managing the shop and the listings directly with JSON.\n\n## Prerequisites:\n\n- Access to the Etsy API is essential. Review [Etsy Quick Start Guide](https://developers.etsy.com/documentation/tutorials/quickstart) for directions on how to get your personal API key. \n- Etspi doesn't provide API key assistance, but it can help with authorization and managing access tokens (explained in the **Authentication** section).\n- Familiarity with JMESPath expressions ([link to JMESPath examples](https://jmespath.org/examples.html)) is recommended to filter and transform output data.\n\n## Features:\n- **Easy Authentication and Authorization:** Etspi guides you through the process of obtaining and managing API tokens.\n- **Automatic Token Management:** Etspi simplifies token maintenance by automatically refreshing access tokens as needed (if configured).\n- **Listing Management:** Handle shop listings and variant inventory directly from the command line.\n- **Flexible Output Filtering:** Tailor output using JMESPath expressions to retrieve only the data you need.\n- **Streamlined Request Formatting:** Transform listing data effortlessly into the appropriate format for draft, listing, or inventory operations.\n\n## Installation:\n\nThe recommended installation method is via `pipx`. Refer to the official `pipx` documentation ([link to pipx doc site](https://pipx.pypa.io/stable/)) for installation and usage instructions.\n\n```bash\npipx install etspi-1.0.1\n```\nIf you plan to use Etspi to obtain API tokens, you will also need to have `openssl` installed or some other means to generate certificates suitable for SSL/TLS to secure HTTP server. Alternatively, you can use dedicated tools like Postman to obtain tokens manually. However, Etspi offers a more convenient approach, and you only need to do this once if you persist the tokens. Etspi will automatically use persited refresh token to get a fresh API token when necessary.\n\n## Authentication:\n\nBefore you can use the app, you will need to obtain an API key from Etsy. You can find more info and how to request a key on the [developer portal](https://www.etsy.com/developers). Familiarize yourself with the Etsy OAuth 2.0 authentication process ([link to Etsy OAuth 2.0 documentation](https://developers.etsy.com/documentation/essentials/authentication)). Etspi assists with authorization and tokens once you've created an app and acquired an API key.\n\n- Note the Keystring from the App settings. You will need it to start the auth flow.\n- In the App settings, you will also need to add a callback URL for the Etspi that will be used in the auth flow.\n - By default, it's https://localhost:10443/etspi, but it can be customized using Etspi flags.\n- Before you start the auth flow with Etspi, you will also need to create a self-signed SSL certificate/key pair for the tool to use.\n - This step is necessary as it is an Etsy requirement that the redirect callback URLs are SSL protected and contain HTTPS prefix.\n - You will need OpenSSL installation for this step.\n - Run the following from the command prompt/terminal to get the cert/key pair and save them to your home Etspi directory.\n - Linux/MacOS:\n\n ```bash\n openssl req -nodes -x509 -newkey rsa:2048 -keyout ~/.etspi/key.pem -out ~/.etspi/cert.pem -days 365\n ```\n - Windows:\n \n ```cmd\n openssl req -nodes -x509 -newkey rsa:2048 -keyout %USERPROFILE%\\.etspi\\key.pem -out %USERPROFILE%\\.etspi\\cert.pem -days 365\n ```\n\n- To start the auth flow for all scopes, default redirect URL, and cert/key files from the prior step:\n ```bash\n etspi auth -tF\n ```\n - `-tF` flag saves tokens to the `Auth.env` file. See `etspi auth --help` for more options.\n\n- The Etspi will compose an Auth URL to start the flow.\n- Authenticate with Etsy and authorize your app with the assigned keystring for access to the requested scopes.\n- Upon authorization completion, Etsy redirects your browser to the defined callback URL, where Etspi is waiting to obtain the tokens.\n- The redirect request contains an authorization code from Etsy that is needed to request the tokens.\n- If successful in obtaining the tokens, they are saved in `Auth.env` file in the `.etspi/` home folder.\n- Most Etspi commands require authorization tokens that can either be pulled from the `Auth.env` file, specified on the command line, or set as environment variables in your shell.\n - E.g. `ETSPI_KEY=YOU_ETSY_APP_KEYSTRING` or `ETSPI_TOKEN=YOUR_AUTH_TOKEN`.\n - Command line options take precedence over the env variables and variables take precedence over the values stored in the `Auth.env` file.\n\n## Listing:\n\n### listing-get\n\nThe most basic use case is to pull listing data by its Id.\n\n```bash\netspi listing-get -i 1800000081\n```\nInclude `-in` flag and option `value` to also include additional data; combine several `values` as needed.\n\n```bash\netspi listing-get -i 1800000081 -in Images -in Shipping\n```\n\nInclude `-q` or `--query` flag and JMESPath expression to filter and shape the output JSON. \n\n```bash\netspi listing-get -i 1800000081 -q \"{ id: listing_id, title: title }\"\n```\n\nEtsy listing JSON structure from `listing-get` command and `draft` or `listing-update` commands are not symmetrical. If you'd like to create a new draft from existing or update a listing, you will likely want to transform the JSON output into the format ready for `draft` or `listing-update` commands. Use `--format-draft` or `--format-update` flags and combine with `-o` flag to save the result into a file you can modify and later use with each command.\n\n```bash\netspi listing-get -i 1800000081 -in Images --format-draft -o my_listing.json\n```\n### draft\n\nCreate a new draft listing from a JSON data source file. To publish your draft you will need to use the `listing-update` command and set the `state` field to `active`. *Expect Etsy to charge the **listing fee** when you activate the draft.*\n\n```bash\netspi draft -s 10000001 -f my_draft_listing.json\n```\n\n### listing-update\n\nLike the `draft` command, you update the listing with the values from a JSON source file specified on the command line.\n\n```bash\netspi listing-update -i 1800000081 -s 10000001 -f my_listing_update.json\n```\n\n### listing-delete\n\nThis is self-explanatory and will delete a listing by Id. Use `-Y` or `--yes` flat to suppress ***confirmation prompt*** before making the API call to delete the listing!\n\n```bash\netspi listing-delete -i 1800000081 -Y\n```\n\n### listing-get-iv\n\nRetrieves the inventory record for a listing by Id.\n\n```bash\netspi listing-get-iv -i 1800000081\n```\n\nInclude `-q` or `--query` flag and JMESPath expression to filter and shape the output JSON. \n\n```bash\netspi listing-get-iv -i 1800000081 -q \"products[?offerings[0].price.amount > `1000`].[product_id, sku]\"\n```\n\nUse `--format-update` and `-o` flags to transform the output into format suitable for `listing-update-iv` command.\n\n```bash\netspi listing-get-iv -i 1800000081 --format-update -o my_listing_inventory.json\n```\n\n### listing-update-iv\n\nUse to update the listing inventory with the values from a JSON source file specified on the command line.\n\n```bash\netspi listing-update-iv -i 1800000081 -f my_listing_update.json\n```\n\n## Note on STDOUT redirects\n\nEtspi console output uses `rich` library `print` which will color code and format JSON for more esthetic and readable output. When using Etspi `--out` you get original formatted JSON which is what you want for subsequent commands and API calls. If you have a need to pipe or redirect Etspi output to a different console app or file, you may want this original JSON and not pretty formatted. In that case, consider using `--out` to STDOUT `-` with `-S` and apply your pipe or redirect this way.\n\n```bash\netspi listing-get -i 1800000081 -in Inventory -S -o - | grep \"sku\"\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI App to manage Etsy shop and listings.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/sov2000/etspi-cli",
"Repository": "https://github.com/sov2000/etspi-cli"
},
"split_keywords": [
"etsy",
" api",
" shop",
" manager"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2d74a69868b3c7cecedfcfd3f8e8e3134db53a6a84bbbbca018a31631e12a90e",
"md5": "2b4b47522ba884ddec93b6b0e8f4cac1",
"sha256": "1f7a055d293f2afb5197906c5417ab86b0c2664febc380d7ce722a159d003e27"
},
"downloads": -1,
"filename": "etspi-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b4b47522ba884ddec93b6b0e8f4cac1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 58822,
"upload_time": "2024-12-20T04:39:52",
"upload_time_iso_8601": "2024-12-20T04:39:52.788580Z",
"url": "https://files.pythonhosted.org/packages/2d/74/a69868b3c7cecedfcfd3f8e8e3134db53a6a84bbbbca018a31631e12a90e/etspi-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6c8ab3625cea5805451ca7884a85b8b45590bd2f02962d5170e6334a3378781f",
"md5": "a8f76b40e4148572e29a46cbef1bf7a5",
"sha256": "72a97b42cfdd4669e8d21554f208b97e139601f90487b2970cee15669fe90d80"
},
"downloads": -1,
"filename": "etspi-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "a8f76b40e4148572e29a46cbef1bf7a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 50283,
"upload_time": "2024-12-20T04:39:54",
"upload_time_iso_8601": "2024-12-20T04:39:54.230101Z",
"url": "https://files.pythonhosted.org/packages/6c/8a/b3625cea5805451ca7884a85b8b45590bd2f02962d5170e6334a3378781f/etspi-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-20 04:39:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sov2000",
"github_project": "etspi-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "etspi"
}
JSON
