{"id":21153724,"url":"https://github.com/openhoat/portainer-sdk","last_synced_at":"2026-04-24T18:35:11.654Z","repository":{"id":41702961,"uuid":"244380575","full_name":"openhoat/portainer-sdk","owner":"openhoat","description":"Portainer API client and command line interface","archived":false,"fork":false,"pushed_at":"2023-01-05T08:50:07.000Z","size":442,"stargazers_count":0,"open_issues_count":19,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-21T08:31:59.877Z","etag":null,"topics":["api","docker","portainer","sdk","tool"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openhoat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-02T13:41:05.000Z","updated_at":"2020-03-14T08:20:06.000Z","dependencies_parsed_at":"2023-02-03T21:30:29.483Z","dependency_job_id":null,"html_url":"https://github.com/openhoat/portainer-sdk","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openhoat%2Fportainer-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openhoat%2Fportainer-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openhoat%2Fportainer-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openhoat%2Fportainer-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openhoat","download_url":"https://codeload.github.com/openhoat/portainer-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243597841,"owners_count":20316844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","docker","portainer","sdk","tool"],"created_at":"2024-11-20T10:59:06.057Z","updated_at":"2025-12-28T18:55:08.385Z","avatar_url":"https://github.com/openhoat.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/openhoat/portainer-sdk.png?branch=master)](https://travis-ci.com/openhoat/portainer-sdk)\n![GitHub package.json version](https://img.shields.io/github/package-json/v/openhoat/portainer-sdk)\n[![Coverage Status](https://coveralls.io/repos/github/openhoat/portainer-sdk/badge.png?branch=master)](https://coveralls.io/github/openhoat/portainer-sdk?branch=master)\n![GitHub](https://img.shields.io/github/license/openhoat/portainer-sdk)\n![GitHub top language](https://img.shields.io/github/languages/top/openhoat/portainer-sdk)\n[![Known Vulnerabilities](https://snyk.io/test/github/openhoat/portainer-sdk/badge.svg)](https://snyk.io/test/github/openhoat/portainer-sdk)\n\nEasy way to deploy and update your containers with a command or an API request through [Portainer](https://www.portainer.io/). \n\n## Portainer SDK\n\nThe goal of this project is to deal with a simple machine-to-machine way to manage docker containers through portainer, it mainly provides :\n- a portainer API client module to integrate portainer and docker features\n- a portainer command (CLI) to easily consume the portainer API from a shell\n\nThis is a draft project...\n\n### Supported features\n\n- [x] show portainer version\n- [x] show portainer info\n- [x] manage remote portainer host\n- [x] portainer authentication\n- [x] saved settings\n- [x] create / pull a docker image\n- [x] remove a docker image\n- [x] list docker images\n- [x] create a docker container\n- [x] get docker container details\n- [x] list docker containers\n- [x] remove a docker container\n- [x] start a docker container\n- [x] stop a docker container\n- [x] deploy a docker container\n- [x] env vars support\n- [ ] add i18n resources\n- [ ] other docker API features...\n- [ ] other portainer API features...\n\n### Command Line Interface\n\n#### Installation\n\n```sh\n$ npm i -g portainer-sdk\n```\n\n#### Usage\n\nThe best way to get started with portainer cli is to simply read the help.\n\n```sh\n$ portainer --help\n```\n\n##### Examples\n\nSome simple examples of usual tasks :\n\n- Pull a docker image\n\n```sh\n$ portainer image-create --from tutum/hello-world\n```\n\n- Create a docker container\n\n```sh\n$ portainer container-create tutum/hello-world \\\n  --name hello-world \\\n  --hostConfig '{ \"RestartPolicy\": { \"Name\": \"unless-stopped\" } }' \\\n  --labels '{ \"traefik.enable\": \"true\", \"traefik.frontend.rule\": \"Host:hello.local.io\", \"traefik.webservice.frontend.entryPoints\": \"http\" }'\n```\n\n- Start the container\n\n```sh\n$ portainer container-start hello-world\n```\n\n- Test the container\n\n```sh\n$ http hello.local.io\n```\n\n- Stop the container\n\n```sh\n$ portainer container-stop hello-world\n```\n\n- Delete the container\n\n```sh\n$ portainer container-remove hello-world\n```\n\n- Delete the image\n\n```sh\n$ portainer image-remove tutum/hello-world\n```\n\n- Redeploy a container\n\n```sh\n$ portainer container-deploy tutum/hello-world hello-world \\                                                                                                     master \n  --hostConfig '{ \"RestartPolicy\": { \"Name\": \"unless-stopped\" } }' \\\n  --labels '{ \"traefik.enable\": \"true\", \"traefik.frontend.rule\": \"Host:hello.local.io\", \"traefik.webservice.frontend.entryPoints\": \"http\" }'\n```\n\n##### Tricks\n\nMore advanced examples :\n\n- Get containers with id\n\n```sh\n$ portainer container-list | jq \"[.[] | {id: .Id, name: .Names[0]}]\" | prettyoutput\n```\n\n- Get images with id\n\n```sh\n$ portainer image-list | jq \"[.[] | {id: .Id, image: .Image}]\" | prettyoutput\n```\n\n- Redeploy a remote image from private registry\n\nExample of a web application using a redis database :\n\n```sh\n$ portainer container-deploy my-image:0.0.1 my-container \\                                                                                     master \n  --registry 'my.private-registry.io' \\\n  --hostConfig '{ \"Links\": [\"redis-server:redis\"], \"RestartPolicy\": { \"Name\": \"unless-stopped\" } }' \\\n  --env '[\"APP_ENV=staging\", \"REDIS_HOST=redis\"]' \\\n  --labels '{ \"traefik.enable\": \"true\", \"traefik.frontend.rule\": \"Host:my-container.mydomain.io\", \"traefik.webservice.frontend.entryPoints\": \"http\" }'\n```\n\n#### Supported environment variables\n\nSome environment variables are supported by the command to override settings, or to facilitate bigger process integration :\n\n- PORTAINER_HOST : base URL of the portainer host to use\n- PORTAINER_JWT : portainer JWT token (obtained in authentication result, and usually available for 8 hours)\n- PORTAINER_USERNAME : username of the portainer account to use when an authentication is needed (to generate a new JWT)\n- PORTAINER_PASSWORD : password of the portainer account to use when an authentication is needed (to generate a new JWT)\n- PORTAINER_DOCKER_REGISTRY : docker registry server hostname\n- ENCRYPTION_KEY : encryption key to use to encrypt / decrypt passwords saved in settings file\n- LOG_LEVEL : log level\n- LANG : preferred lang to use (aliases : LC_ALL, LC_MESSAGES, LANGUAGE)\n\n### SDK\n\n#### portainer\n\n##### auth\n\nAuthenticate a account portainer account and returns a JWT, usually available for 8 hours.\n\n- params : \n\n    - username : (string, optionnal) portainer account username\n    - password?: (string, optionnal) portainer account password\n    - host: (string, optionnal) portainer host\n\n- async result :\n\n    - jwt : (string) generated JWT token\n    - statusCode : (number) HTTP status code\n    - body: (any) response body\n\n##### getHostOptions\n\nGet portainer host options.\n\n- params :\n\n    - host: (string, optionnal) portainer host\n\n- result :\n\n    - saveSettings: (boolean) true if settings are saved\n    - defaultHost : (string)\n    - jwt: (string, optionnal) last generated JWT\n    - hosts: PortainerHostsOptions; \n\n##### setHostOptions\n\nSet portainer host options.\n\n- params :\n\n    - key: string\n    - value: any\n    - host?: string\n\n- no result\n\n#### portainer.docker\n\n##### container\n\n\u003e TODO\n\n- params :\n\n    - id: string\n    - host?: string\n\n- result : Promise\u003cResponse\u003e\n\n##### containers\n\n\u003e TODO\n\n- params : host?: string\n\n- result : Promise\u003cResponse\u003e\n\n##### createContainer\n\n\u003e TODO\n\n- params : \n\n    - image : string\n    - hostConfig? : any\n    - labels? : any\n    - name? : string\n    - env? : any\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\n##### createImage\n\n\u003e TODO\n\n- params :\n\n    - from : string\n    - registry? : string\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\n##### deployContainer\n\n\u003e TODO\n\n- params :\n\n    - image : string\n    - name : string\n    - hostConfig? : any\n    - labels? : any\n    - env? : any\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\n##### images\n\n\u003e TODO\n\n- params :\n\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\n##### info\n\n\u003e TODO\n\n- params :\n\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\n##### removeContainer\n\n\u003e TODO\n\n- params :\n\n    - id : string\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string    \n\n- result : Promise\u003cResponse\u003e\n\n##### removeImage\n\n\u003e TODO\n\n- params :\n\n    - image : string\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\n##### startContainer\n\n\u003e TODO\n\n- params :\n\n    - id : string\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\n##### stopContainer\n\n\u003e TODO\n\n- params :\n\n    - id : string\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\n##### version\n\n\u003e TODO\n\n- params :\n\n    - data? : any\n    - query? : any\n    - headers? : any\n    - host? : string\n    - jwt? : string\n\n- result : Promise\u003cResponse\u003e\n\nEnjoy !\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenhoat%2Fportainer-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenhoat%2Fportainer-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenhoat%2Fportainer-sdk/lists"}