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 local Hex configuration.

mix hex.config KEY [VALUE]

Config keys

  • 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 registry 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
  • https_proxy - HTTPS proxy server. Can be overridden by setting the environment variable HTTPS_PROXY
  • http_concurrency - Limits the number of concurrent HTTP requests in flight. Can be overridden by setting the environment variable HEX_HTTP_CONCURRENCY (Default: 8)
  • http_timeout - Sets the timeout for HTTP requests in seconds. Can be overridden by setting the environment variable HEX_HTTP_TIMEOUT

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
  • --organization ORGANIZATION - The organization the package belongs to

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.

Command line options

  • --organization ORGANIZATION - The organization the package belongs to

hex.organization

Manages the list of authorized Hex.pm organizations.

Organizations is a feature of Hex.pm to host and manage private packages. See https://hex.pm/docs/private for more information.

By authorizing a new organization a new key is created for fetching packages from the organizations repository and the repository and key is stored on the local machine.

To use a package from an organization add organization: "my_organization" to the dependency declaration in mix.exs:

{:plug, "~> 1.0", organization: "my_organization"}

Authorize an organization

mix hex.organization auth NAME

Command line options

  • --key KEY - Hash of key used to authenticate HTTP requests to repository, if omitted will generate a new key with your account credentials. This flag is useful if you have a key pre-generated with mix hex.organization key and want to authenticate on a CI server or similar system

Deauthorize and remove an organization

mix hex.organization deauth NAME

Generate a repository autentication key

This command is useful to pre-generate keys for use with mix hex.organization auth NAME --key KEY on CI servers or similar systems. It returns the hash of the generated key that you can pass to auth NAME --key KEY

mix hex.organization key NAME

List all authorized organizations

mix hex.organization list

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

Command line options

  • --organization ORGANIZATION - The organization the package belongs to

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
  • --organization ORGANIZATION - The organization the package belongs to

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.
  • :organization - Set this if you are publishing to an organization instead of the default public hex.pm.
  • :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.

The repository is where packages and the registry of packages is stored. You can fetch packages from multiple different repositories and packages can depend on packages from other repositories. To use a package from another repository than the global default hexpm 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 ....

A repository configured from an organization will have hexpm: prefixed to its name. To depend on packages from an organization add repo: "hexpm:my_organization" to the dependency declaration or simply organization: "my_organization".

To configure organizations, see the hex.organization task.

Add a repo

mix hex.repo add NAME URL

Command line options

  • --public-key PATH - Path to public key used to verify the registry (optional).
  • --auth-key KEY - Key used to authenticate HTTP requests to repository (optional).

Set config for repo

mix hex.repo set NAME --url URL
mix hex.repo set NAME --public-key PATH
mix hex.repo set NAME --auth-key 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
  • --organization ORGANIZATION - The organization the package belongs to

hex.search

Displays packages matching the given search query.

mix hex.search PACKAGE

Command line options

  • --organization ORGANIZATION - The organization the package belongs to

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

Revoke key

Removes given API key from account.

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

mix hex.user key --revoke key_name

Revoke all keys

Revoke all API keys from your account.

mix hex.user key --revoke-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