Command Help



hof has several commands typically run during daily development. The first-example will introduce you to these commands and each has a dedicated section for the topic as well.

hof

Top level commands and help message

hof help

$ hof help

hof - the high code framework

  Learn more at https://docs.hofstadter.io

Usage:
  hof [flags] [command] [args]

Main commands:
  datamodel             manage, diff, and migrate your data models
  gen                   modular and composable code gen: CUE & data + templates = _
  flow                  run CUE pipelines with the hof/flow DAG engine
  fmt                   format any code and manage the formatters
  mod                   polyglot dependency management based on go mods and MVS

Additional commands:
  help                  help about any command
  update                check for new versions and run self-updates
  version               print detailed version information
  completion            generate completion helpers for your terminal
  feedback              send feedback, bug reports, or any message

Flags:
  -h, --help             help for hof
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -v, --verbosity int    set the verbosity of output

Use "hof [command] --help / -h" for more information about a command.

hof / datamodel

Used for data model management (dm for short)

See the Data Modeling section for details.

hof help datamodel

$ hof help datamodel

Data models are sets of models which are used in many hof processes and modules.

At their core, they represent the most abstract representation for objects and
their relations in your applications. They are extended and annotated to add
context fot their usage in different code generators: (DB vs Server vs Client).

Beyond representing models in their current form, a history is maintained so that:
  - database migrations can be created and managed
  - servers can handle multiple model versions
  - clients can implement feature flags
Much of this is actually handled by code generators and must be implemented there.
Hof handles the core data model definitions, history, and snapshot creation.

Usage:
  hof datamodel [command]

Aliases:
  datamodel, dm

Available Commands:
  checkpoint  create a snapshot of the data model
  diff        show the diff between data model version
  history     list the snapshots for a data model
  info        print details for a data model
  list        print available data models
  log         show the history of diffs for a data model

Flags:
  -d, --datamodel strings   Datamodels for the datamodel commands
  -f, --format string       Pick format from Cuetils (default "_")
  -h, --help                help for datamodel
  -m, --model strings       Models for the datamodel commands
  -o, --output string       Output format [table,cue] (default "table")
  -s, --since string        Timestamp to filter since
  -u, --until string        Timestamp to filter until

Global Flags:
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -v, --verbosity int    set the verbosity of output

Use "hof datamodel [command] --help" for more information about a command.

hof / gen

Create one-liners to generate files with data, CUE, and templates or use composable generators to build out advanced applications.

See the code gen docs to learn more

hof help flow

$ hof help gen

hof unifies CUE with Go's text/template system and diff3
  create on-liners to generate any file from any 
  build reusable and modular generators
  edit and regenerate those files while keeping changes

# Render a template
  hof gen input.cue -T template.txt
  hof gen input.yaml schema.cue -T template.txt > output.txt

# Add partials to the template context
  hof gen input.cue -T template.txt -P partial.txt

# The template flag as code gen mappings
  hof gen input.cue -T ... -T ...

  # Generate multiple templates at once
  -T templateA.txt -T templateB.txt

  # Select a sub-input value by CUEpath
  -T templateA.txt:foo
  -T templateB.txt:sub.val

  # Choose a schema with @
  -T templateA.txt:foo@Foo
  -T templateB.txt:sub.val@schemas.val

  # Writing to file with = (semicolon)
  -T templateA.txt=a.txt
  -T templateB.txt:sub.val@schema=b.txt

  # Templated output path, braces need quotes
  -T templateA.txt:='{{ .name | lower }}.txt'

  # Repeated templates are used when
  # 1. the output has a '[]' prefix
  # 2. the input is a list or array
  #   The template will be processed per entry
  #   This also requires using a templated outpath
  -T template.txt:items='[]out/{{ .filepath }}.txt'

  # Output everything to a directory (out name is the same)
  -O out -T types.go -T handlers.go

  # Watch files and directories, doing full or Xcue-less reloads
  -W *.cue -X *.go -O out -T types.go -T handlers.go

# Turn any hof gen flags into a reusable generator module
  hof gen [entrypoints] flags... --as-module [name]
  hof gen [entrypoints] -G [name]

# Bootstrap a new generator module
  hof gen --init github.com/hofstadter-io/demos

# Learn about writing templates, with extra functions and helpers
  https://docs.hofstadter.io/code-generation/template-writing/

# Check the tests for complete examples
  https://github.com/hofstadter-io/hof/tree/_dev/test/render

# Compose code gen mappings into reusable modules with
  hof gen app.cue -G frontend -G backend -G migrations -T ...
  https://docs.hofstadter.io/first-example/

Usage:
  hof gen [files...] [flags]

Aliases:
  gen, G

Flags:
      --as-module string      <github.com/username/<name>> like value for the generator module made from the given flags
  -D, --diff3                 enable diff3 support for custom code
  -G, --generator strings     generator tags to run, default is all, or none if -T is used
  -h, --help                  help for gen
      --init string           <name> to bootstrap a new genarator module
  -l, --list                  list available generators
  -O, --outdir string         base directory to write all output u
  -P, --partial strings       file globs to partial templates to register with the templates
  -s, --stats                 print generator statistics
  -T, --template strings      template mapping to render, see help for format
  -w, --watch                 run in watch mode, regenerating when files change, implied by -W/X
  -X, --watch-fast strings    filepath globs to watch for changes and trigger fast regen
  -W, --watch-globs strings   filepath globs to watch for changes and trigger full regen

Global Flags:
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -v, --verbosity int    set the verbosity of output

hof / flow

Build workflows and scripts with CUE and a DAG engine

See the flow docs to learn more

hof help flow

$ hof help flow

run CUE pipelines with the hof/flow DAG engine

Use hof/flow to transform data, call APIs, work with DBs,
read and write files, call any program, handle events,
and much more.

'hof flow' is very similar to 'cue cmd' and built on the same flow engine.
Tasks and dependencies are inferred.
Hof flow has a slightly different interface and more task types.

Docs: https://docs.hofstadter.io/data-flow

Example:

  @flow()

  call: {
    @task(api.Call)
    req: { ... }
    resp: {
      statusCode: 200
      body: string
    }
  }

  print: {
    @task(os.Stdout)
    test: call.resp
  }

Arguments:
  cue entrypoints are the same as the cue cli
  @path/name  is shorthand for -f / --flow should match the @flow(path/name)
  +key=value  is shorthand for -t / --tags and are the same as CUE injection tags

  arguments can be in any order and mixed

@flow() indicates a flow entrypoint
  you can have many in a file or nested values
  you can run one or many with the -f flag

@task() represents a unit of work in the flow dag
  intertask dependencies are autodetected and run appropriately
  hof/flow provides many built in task types
  you can reuse, combine, and share as CUE modules, packages, and values

Usage:
  hof flow [cue files...] [@flow/name...] [+key=value] [flags]

Aliases:
  flow, f

Flags:
  -d, --docs           print pipeline docs
  -f, --flow strings   flow labels to match and run
  -h, --help           help for flow
  -l, --list           list available pipelines
      --progress       print task progress as it happens
  -s, --stats          Print final task statistics
  -t, --tags strings   data tags to inject before run

Global Flags:
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -v, --verbosity int    set the verbosity of output

hof / mod

Manage a MVS (Golang) style modules and dependencies. Create custom module systems with a single config file.

Also, more typically, used as a stop gap for CUE modules until cue mod is implemented.

typical usage

# initialize a new module
hof mod init cue hof.io/docs/example

# download dependencies
hof mod vendor cue
hof help mod

$ hof help mod

hof mod is a flexible tool and library based on Go mods.

Use and create module systems with Minimum Version Selection (MVS) semantics
and manage dependencies go mod style. Mix any set of language, code bases,
git repositories, package managers, and subdirectories.


### Features

- Based on go mods MVS system, aiming for 100% reproducible builds.
- Recursive dependencies, version resolution, and code instrospection.
- Custom module systems with custom file names and vendor directories.
- Control configuration for naming, vendoring, and other behaviors.
- Polyglot support for multiple module systems and multiple languages within one tool.
- Works with any git system and supports the main features from go mods.
- Convert other vendor and module systems to MVS or just manage their files with MVS.
- Private repository support for GitHub, GitLab, Bitbucket, and git+SSH.


### Usage

# Print known languages in the current directory
hof mod info

# Initialize this folder as a module
hof mod init <lang> <module-path>

# Add your requirements
vim <lang>.mods  # go.mod like file

# Pull in dependencies, no args discovers by *.mods and runs all
hof mod vendor [langs...]

# See all of the commands
hof mod help


### Module File

The module file holds the requirements for project.
It has the same format as a go.mod file.

---
# These are like golang import paths
#   i.e. github.com/hofstadter-io/hof
module <module-path> 

# Information about the module type / version
#  some systems that take this into account
# go = 1.14
<lang> = <version>

# Required dependencies section
require (
	# <module-path> <module-semver>
	github.com/hof-lang/cuemod--cli-golang v0.0.0      # This is latest on HEAD
	github.com/hof-lang/cuemod--cli-golang v0.1.5      # This is a tag v0.1.5 (can omit 'v' in tag, but not here)
)

# replace <module-path> => <module-path|local-path> [version]
replace github.com/hof-lang/cuemod--cli-golang => github.com/hofstadter-io/hofmod-cli-golang v0.2.0
replace github.com/hof-lang/cuemod--cli-golang => ../../cuelibs/cuemod--cli-golang
---


### Authentication and private modules

hof mod prefers authenticated requests when fetching dependencies.
This increase rate limits with hosts and supports private modules.
Both token and sshkey base methods are supported.

If you are using credentials, then private modules can be transparent.
An ENV VAR like GOPRIVATE and CUEPRIVATE can be used to require credentials.

The following ENV VARS are used to set credentials.

GITHUB_TOKEN
GITLAB_TOKEN
BITBUCKET_TOKEN or BITBUCKET_USERNAME / BITBUCKET_PASSWORD *

SSH keys will be looked up in the following ~/.ssh/config, /etc/ssh/config, ~/.ssh/in_rsa

You can configure the SSH key with

HOF_SSHUSR and HOF_SSHKEY

* The bitbucket method will depend on the account type and enterprise license.


### Custom Module Systems

.mvsconfig.cue allows you to define custom module systems.
With some simple configuration, you can create and control
and vendored module system based on go mods.
You can also define global configurations.

See the ./lib/mod/langs in the repository for examples.

### Motivation

- MVS has better semantics for vendoring and gets us closer to 100% reproducible builds.
- JS and Python can have MVS while still using the remainder of the tool chains.
- Prototype for cuelang module and vendor management.
- We need a module system for our [hof-lang](https://hof-lang.org) project.

Usage:
  hof mod [command]

Aliases:
  mod, m

Available Commands:
  info        print info about languages and modders known to hof mod
  init        initialize a new module in the current directory
  vendor      make a vendored copy of dependencies

Flags:
  -h, --help   help for mod

Global Flags:
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -v, --verbosity int    set the verbosity of output

Use "hof mod [command] --help" for more information about a command.
2022 Hofstadter, Inc