Mix tasks

hex

Prints Hex tasks and their information.

 mix hex

See mix help hex.config to see all available configuration options.

hex.audit

Shows all Hex dependencies that have been marked as retired.

Retired packages are no longer recommended to be used by their maintainers. The task will display a message describing the reason for retirement and exit with a non-zero code if any retired dependencies are found.

hex.build

Builds a new local version of your package.

The package .tar file is created in the current directory, but is not pushed to the repository. An app named foo at version 1.2.3 will be built as foo-1.2.3.tar.

mix hex.build

Configuration

  • :app - Package name (required).

  • :version - Package version (required).

  • :deps - List of package dependencies (see Dependencies below).

  • :description - Short description of the project.

  • :package - Hex specific configuration (see Package configuration below).

Dependencies

Dependencies are defined in mix’s dependency format. But instead of using :git or :path as the SCM :package is used.

defp deps do
  [ {:ecto, "~> 0.1.0"},
    {:postgrex, "~> 0.3.0"},
    {:cowboy, github: "extend/cowboy"} ]
end

As can be seen Hex package dependencies works alongside git dependencies. Important to note is that non-Hex dependencies will not be used during dependency resolution and neither will be they listed as dependencies of the package.

Package configuration

Additional package metadata is optional, but highly recommended.

  • :name - Set this if the package name is not the same as the application name.

  • :files - List of files and directories to include in the package, can include wildcards. Defaults to ["lib", "priv", "mix.exs", "README*", "readme*", "LICENSE*", "license*", "CHANGELOG*", "changelog*", "src"].

  • :maintainers - List of names and/or emails of maintainers.

  • :licenses - List of licenses used by the package.

  • :links - Map of links relevant to the package.

  • :build_tools - List of build tools that can build the package. Hex will try to automatically detect the build tools based on the files in the package. If a “rebar” or “rebar.config” file is present Hex will mark it as able to build with rebar. This detection can be overridden by setting this field.

hex.config

Reads, updates or deletes Hex configuration keys.

mix hex.config KEY [VALUE]

Config keys

  • username - Hex username
  • key - Hex API key
  • api_url - Hex API URL. Can be overridden by setting the environment variable HEX_API_URL (Default: "https://hex.pm/api")
  • offline - If set to true Hex will not fetch the regsitry or packages and will instead use locally cached files if they are available. Can be overridden by setting the environment variable HEX_OFFLINE (Default: false)
  • unsafe_https - If set to true Hex will not verify HTTPS certificates. Can be overridden by setting the environment variable HEX_UNSAFE_HTTPS (Default: false)
  • unsafe_registry - If set to true Hex will not verify the registry signature against the repository’s public key. Can be overridden by setting the environment variable HEX_UNSAFE_REGISTRY (Default: false)
  • http_proxy - HTTP proxy server. Can be overridden by setting the environment variable HTTP_PROXY (Default: nil)
  • https_proxy - HTTPS proxy server. Can be overridden by setting the environment variable HTTPS_PROXY (Default: nil)
  • http_concurrency - Limits the number of concurrent HTTP requests in flight. Can be overridden by setting the environment variable HEX_HTTP_CONCURRENCY (Default: 8)

Command line options

  • --delete - Remove a specific config key

hex.docs

Fetches or opens documentation of a package.

mix hex.docs fetch PACKAGE [VERSION]

It will retrieve and decompress the specified version of the documentation for a package. If you do not specify the version argument, this task will retrieve the latest documentation available in the mirror.

mix hex.docs open PACKAGE [VERSION]

Command line options

  • --offline - Open a local version available in your filesystem
  • --module Some.Module - Open a specified module documentation page inside desired package

It will open the specified version of the documentation for a package in a Web browser. If you do not specify the version argument, this task will open the latest documentation.

hex.info

Prints Hex package or system information.

mix hex.info [PACKAGE [VERSION]]

If package is not given, print system information. This includes when registry was last updated and current system version.

If package is given, print information about the package. This includes all released versions and package metadata.

If package and version is given print release information. This includes remote Git URL and Git ref, and all package dependencies.

hex.outdated

Shows all Hex dependencies that have newer versions in the registry.

By default, it only shows top-level packages explicitly listed in the mix.exs file. All outdated packages can be displayed by using the --all command line option.

If a dependency name is given all requirements on that dependency, from the entire dependency tree, are listed. This is useful if you are trying to figure why a package isn’t updating when you run mix deps.update.

mix hex.outdated [APP]

Command line options

  • --all - shows all outdated packages, including children of packages defined in mix.exs
  • --pre - include pre-releases when checking for newer versions

hex.owner

Adds, removes or lists package owners.

Package owners have full permissions to the package. They can publish and revert releases and even remove other package owners.

Add owner

Adds an owner to package by specifying the package name and email of the new owner.

mix hex.owner add PACKAGE EMAIL

Remove owner

Removes an owner to package by specifying the package name and email of the new owner.

mix hex.owner remove PACKAGE EMAIL

List owners

Lists all owners of given package.

mix hex.owner list PACKAGE

List owned packages

Lists all packages owned by the current user.

mix hex.owner packages

hex.publish

Publishes a new version of your package and its documentation.

mix hex.publish package

If it is a new package being published it will be created and the user specified in username will be the package owner. Only package owners can publish.

A published version can be amended or reverted with --revert up to one hour after its publication. Older packages can not be reverted.

mix hex.publish docs

The documentation will be accessible at https://hexdocs.pm/my_package/1.0.0, https://hexdocs.pm/my_package will always redirect to the latest published version.

Documentation will be generated by running the mix docs task. ex_doc provides this task by default, but any library can be used. Or an alias can be used to extend the documentation generation. The expected result of the task is the generated documentation located in the doc/ directory with an index.html file.

Note that if you want to publish a new version of your package and its documentation in one step, you can use the following shorthand:

mix hex.publish

Command line options

  • --revert VERSION - Revert given version

Configuration

  • :app - Package name (required).

  • :version - Package version (required).

  • :deps - List of package dependencies (see Dependencies below).

  • :description - Short description of the project.

  • :package - Hex specific configuration (see Package configuration below).

Dependencies

Dependencies are defined in mix’s dependency format. But instead of using :git or :path as the SCM :package is used.

defp deps do
  [{:ecto, "~> 0.1.0"},
  {:postgrex, "~> 0.3.0"},
  {:cowboy, github: "extend/cowboy"}]
end

As can be seen Hex package dependencies works alongside git dependencies. Important to note is that non-Hex dependencies will not be used during dependency resolution and neither will be they listed as dependencies of the package.

Package configuration

Additional metadata of the package can optionally be defined, but it is very recommended to do so.

  • :name - Set this if the package name is not the same as the application name.

  • :files - List of files and directories to include in the package, can include wildcards. Defaults to ["lib", "priv", "mix.exs", "README*", "readme*", "LICENSE*", "license*", "CHANGELOG*", "changelog*", "src"].

  • :maintainers - List of names and/or emails of maintainers.

  • :licenses - List of licenses used by the package.

  • :links - Map of links relevant to the package.

  • :build_tools - List of build tools that can build the package. Hex will try to automatically detect the build tools, it will do this based on the files in the package. If a “rebar” or “rebar.config” file is present Hex will mark it as able to build with rebar. This detection can be overridden by setting this field.

hex.repo

Manages the list of available Hex repositories.

To use a package from another repository add repo: :my_repo to the dependency declaration in mix.exs:

{:plug, "~> 1.0", repo: :my_repo}

By default all dependencies of plug will also be fetched from :my_repo unless plug has declared otherwise in its dependency definition.

To use packages from :my_repo you need to add it to your configuration first. You do that by calling mix hex.repo my_repo https://myrepo.example.com.

The default repo is called :hexpm and points to https://repo.hex.pm. This can be overridden by using mix hex.repo set ....

Child dependencies will always be fetched from the same repository as the parent package. To override which repository a package is fetched from add the package to your dependencies and add the :repo option.

Add a repo

mix hex.repo add NAME URL [PUBLIC_KEY_PATH [AUTH_KEY]]

Set config for repo

mix hex.repo set url NAME URL
mix hex.repo set public_key NAME PUBLIC_KEY_PATH
mix hex.repo set auth_key NAME AUTH_KEY

Remove repo

mix hex.repo remove NAME

Show repo config

mix hex.repo show NAME

List all repos

mix hex.repo list

hex.retire

Retires a package version.

mix hex.retire PACKAGE VERSION REASON

mix hex.retire PACKAGE VERSION --unretire

Mark a package as retired when you no longer recommend it’s usage. A retired is still resolvable and usable but it will be flagged as retired in the repository and a message will be displayed to users when they use the package.

Retirement reasons

  • renamed - The package has been renamed, including the new package name in the message
  • deprecated - The package has been deprecated, if there’s a replacing package include it in the message
  • security - There are security issues with this package
  • invalid - The package is invalid, for example it does not compile correctly
  • other - Any other reason not included above, clarify the reason in the message

Command line options

  • --message "MESSAGE" - Optional message (up to 140 characters) clarifying the retirement reason

hex.search

Displays packages matching the given search query.

mix hex.search PACKAGE

hex.user

Hex user tasks.

Register a new user

mix hex.user register

Print the current user

mix hex.user whoami

Authorize a new user

Authorizes a new user on the local machine by generating a new API key and storing it in the Hex config.

mix hex.user auth

Deauthorize the user

Deauthorizes the user from the local machine by removing the API key from the Hex config.

mix hex.user deauth

Reencrypt API key

Updates the passphrase for the locally stored API key.

mix hex.user passphrase

Remove key

Removes given API key from account.

The key can no longer be used to authenticate API requests.

mix hex.user key --remove key_name

Remove all keys

Remove all API keys from your account.

mix hex.user key --remove-all

List keys

Lists all API keys associated with your account.

mix hex.user key --list

Test authentication

Tests if authentication works with the stored API key.

mix hex.user test

Reset user password

mix hex.user reset password