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 they be 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", ".formatter.exs", "mix.exs", "README*", "readme*", "LICENSE*", "license*", "CHANGELOG*", "changelog*", "src"].
  • :exclude_patterns - List of patterns matching files and directories to exclude from the package.
  • :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.

Command line options

  • --unpack - Builds the tarball and unpacks contents into a directory. Useful for making sure the tarball contains all needed files before publishing. See --output below for setting the output path.

  • -o, --output - Sets output path. When used with --unpack it means the directory (Default: <app>-<version>). Otherwise, it specifies tarball path (Default: <app>-<version>.tar)

hex.config

Reads, updates or deletes local Hex configuration.

mix hex.config KEY [VALUE]

Config keys

  • api_key - Your API key. If you are authenticated this config will override the API key used for your authenticated user. Can be also be overridden by setting the environment variable 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 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

HEX_HOME environment variable can be set to point to the directory where Hex stores the cache and configuration (Default: ~/.hex)

Command line options

  • --delete - Remove a specific config key

hex.docs

Fetches or opens documentation of a package.

If no version is specified, defaults to version used in the current mix project. If called outside of a mix project or the dependency is not used in the current mix project, defaults to the latest version.

Fetch documentation for all dependencies in the current mix project

mix hex.docs fetch

Fetch documentation for offline use

Fetches documentation for the specified package that you can later open with mix hex.docs offline.

mix hex.docs fetch PACKAGE [VERSION]

Open a browser window with offline documentation

mix hex.docs offline PACKAGE [VERSION]

Open a browser window with online documentation

mix hex.docs online PACKAGE [VERSION]

Command line options

  • --module Some.Module - Open a specified module documentation page inside desired package
  • --organization ORGANIZATION - The organization the package belongs to
  • --latest - Looks for the latest release of a package

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.

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 default you will be authorized to all your applications when running mix hex.user auth and this is the recommended approach. This task is mainly provided for a CI and build systems where access to an organization is needed without authorizing a user.

By authorizing a new organization a new key is created for fetching packages from the organizations repository and the repository 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

This command will generate an API key used to authenticate access to the organization. See the hex.user tasks to list and control all your active API keys.

mix hex.organization auth ORGANIZATION  [--key KEY] [--key-name KEY_NAME]

Deauthorize and remove an organization

mix hex.organization deauth NAME

List all authorized organizations

This command will only list organizations you have authorized with this task, it will not list organizations you have access to by having authorized with mix hex.user auth.

mix hex.organization list

Generate organization key

This command is useful to pre-generate keys for use with mix hex.organization auth ORGANIZATION --key KEY on CI servers or similar systems. It returns the hash of the generated key that you can pass to auth ORGANIZATION --key KEY. Unlike the hex.user key commands, a key generated with this command is owned by the organization directly, and not the user that generated it. This makes it ideal for shared environments such as CI where you don’t want to give access to user-specific resources and the user’s organization membership status won’t affect key. By default this command sets the repository permission which allows read-only access to the repository, it can be overriden with the --permission flag.

mix hex.organization key ORGANIZATION generate [--key-name KEY_NAME] [--permission PERMISSION]

Revoke key

Removes given key from organization.

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

mix hex.organization key ORGANIZATION revoke KEY_NAME

Revoke all keys

Revoke all keys from the organization.

mix hex.organization key ORGANIZATION revoke --all

List keys

Lists all keys associated with the organization.

mix hex.organization key ORGANIZATION list

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

  • --key-name KEY_NAME - By default Hex will base the key name on your machine’s hostname and the organization name, use this option to give your own name.

  • --permission PERMISSION - Sets the permissions on the key, this option can be given multiple times, possibly values are:

    • api:read - API read access.
    • api:write - API write access.
    • repository - Access to the organization’s repository.

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, if the last version is reverted the package is removed
  • --organization ORGANIZATION - The organization the package belongs to
  • --yes - Publishes the package without any confirmation prompts

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 they be 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"].
  • :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 add 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 package 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.

If you are authenticated it will additionally search all organizations you are member of.

mix hex.search PACKAGE

Command line options

  • --organization ORGANIZATION - Search packages in specific organization

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 [--key-name KEY_NAME]

Command line options

  • --key-name KEY_NAME - By default Hex will base the key name on your machine’s hostname, use this option to give your own name.

Deauthorize the user

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

mix hex.user deauth

Generate user key

Generates an unencrypted API key for your account. Keys generated by this command will be owned by you and will give access to your private resources, do not share this key with anyone. For keys that will be shared by organization members use mix hex.organization key instead. By default this command sets the api:write permission which allows write access to the API, it can be overriden with the --permission flag.

mix hex.user key generate

Command line options

  • --key-name KEY_NAME - By default Hex will base the key name on your machine’s hostname, use this option to give your own name.

  • --permission PERMISSION - Sets the permissions on the key, this option can be given multiple times, possible values are:

    • api:read - API read access.
    • api:write - API write access.
    • repository:ORGANIZATION_NAME - Access to given organization repository.
    • repositories - Access to repositories for all organizations you are member of.

Revoke key

Removes given 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 keys from your account.

mix hex.user key revoke --all

List keys

Lists all keys associated with your account.

mix hex.user key list

Reset user account password

Starts the process for reseting account password.

mix hex.user reset_password account

Reset local password

Updates the local password for your local authentication credentials.

mix hex.user reset_password local