{"id":13491255,"url":"https://github.com/kolypto/j2cli","last_synced_at":"2025-10-21T19:13:38.970Z","repository":{"id":18123461,"uuid":"21200929","full_name":"kolypto/j2cli","owner":"kolypto","description":"Jinja2 Command-Line Tool, reworked","archived":false,"fork":true,"pushed_at":"2024-02-12T00:17:53.000Z","size":95,"stargazers_count":738,"open_issues_count":37,"forks_count":81,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-14T08:00:03.771Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://pypi.python.org/pypi/j2cli","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mattrobenolt/jinja2-cli","license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kolypto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-25T11:35:31.000Z","updated_at":"2024-04-02T19:04:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kolypto/j2cli","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolypto%2Fj2cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolypto%2Fj2cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolypto%2Fj2cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolypto%2Fj2cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kolypto","download_url":"https://codeload.github.com/kolypto/j2cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245996336,"owners_count":20707219,"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":[],"created_at":"2024-07-31T19:00:54.960Z","updated_at":"2025-10-21T19:13:33.667Z","avatar_url":"https://github.com/kolypto.png","language":"Python","funding_links":[],"categories":["General Purpose Preprocessor","Python","others"],"sub_categories":["Snippets Manager"],"readme":"[![Build Status](https://travis-ci.org/kolypto/j2cli.svg)](https://travis-ci.org/kolypto/j2cli)\n[![Pythons](https://img.shields.io/badge/python-2.6%20%7C%202.7%20%7C%203.4%E2%80%933.7%20%7C%20pypy-blue.svg)](.travis.yml)\n\nProject Closed\n===============\n\nThis project is not maintained anymore.\n\nHere are some actively maintained forks:\n\n* \u003chttps://github.com/kpfleming/jinjanator\u003e\n* \u003chttps://github.com/mattrobenolt/jinja2-cli\u003e\n* \u003chttps://github.com/m000/jj2cli\u003e\n\n\u003chr /\u003e\n\nj2cli - Jinja2 Command-Line Tool\n================================\n\n`j2cli` is a command-line tool for templating in shell-scripts,\nleveraging the [Jinja2](http://jinja.pocoo.org/docs/) library.\n\nFeatures:\n\n* Jinja2 templating\n* INI, YAML, JSON data sources supported\n* Allows the use of environment variables in templates! Hello [Docker](http://www.docker.com/) :)\n\nInspired by [mattrobenolt/jinja2-cli](https://github.com/mattrobenolt/jinja2-cli)\n\n## Installation\n\n```\npip install j2cli\n```\n\nTo enable the YAML support with [pyyaml](http://pyyaml.org/):\n\n```\npip install j2cli[yaml]\n```\n\n## Tutorial\n\nSuppose, you want to have an nginx configuration file template, `nginx.j2`:\n\n```jinja2\nserver {\n  listen 80;\n  server_name {{ nginx.hostname }};\n\n  root {{ nginx.webroot }};\n  index index.htm;\n}\n```\n\nAnd you have a JSON file with the data, `nginx.json`:\n\n```json\n{\n    \"nginx\":{\n        \"hostname\": \"localhost\",\n        \"webroot\": \"/var/www/project\"\n    }\n}\n```\n\nThis is how you render it into a working configuration file:\n\n```bash\n$ j2 -f json nginx.j2 nginx.json \u003e nginx.conf\n```\n\nThe output is saved to `nginx.conf`:\n\n```\nserver {\n  listen 80;\n  server_name localhost;\n\n  root /var/www/project;\n  index index.htm;\n}\n```\n\nAlternatively, you can use the `-o nginx.conf` option.\n\n## Tutorial with environment variables\n\nSuppose, you have a very simple template, `person.xml`:\n\n```jinja2\n\u003cdata\u003e\u003cname\u003e{{ name }}\u003c/name\u003e\u003cage\u003e{{ age }}\u003c/age\u003e\u003c/data\u003e\n```\n\nWhat is the easiest way to use j2 here?\nUse environment variables in your bash script:\n\n```bash\n$ export name=Andrew\n$ export age=31\n$ j2 /tmp/person.xml\n\u003cdata\u003e\u003cname\u003eAndrew\u003c/name\u003e\u003cage\u003e31\u003c/age\u003e\u003c/data\u003e\n```\n\n## Using environment variables\n\nEven when you use yaml or json as the data source, you can always access environment variables\nusing the `env()` function:\n\n```jinja2\nUsername: {{ login }}\nPassword: {{ env(\"APP_PASSWORD\") }}\n```\n\n\n## Usage\n\nCompile a template using INI-file data source:\n\n    $ j2 config.j2 data.ini\n\nCompile using JSON data source:\n\n    $ j2 config.j2 data.json\n\nCompile using YAML data source (requires PyYAML):\n\n    $ j2 config.j2 data.yaml\n\nCompile using JSON data on stdin:\n\n    $ curl http://example.com/service.json | j2 --format=json config.j2\n\nCompile using environment variables (hello Docker!):\n\n    $ j2 config.j2\n\nOr even read environment variables from a file:\n\n    $ j2 --format=env config.j2 data.env\n\nOr pipe it: (note that you'll have to use the \"-\" in this particular case):\n\n    $ j2 --format=env config.j2 - \u003c data.env\n\n\n# Reference\n`j2` accepts the following arguments:\n\n* `template`: Jinja2 template file to render\n* `data`: (optional) path to the data used for rendering.\n    The default is `-`: use stdin. Specify it explicitly when using env!\n\nOptions:\n\n* `--format, -f`: format for the data file. The default is `?`: guess from file extension.\n* `--import-env VAR, -e EVAR`: import all environment variables into the template as `VAR`.\n    To import environment variables into the global scope, give it an empty string: `--import-env=`.\n    (This will overwrite any existing variables!)\n* `-o outfile`: Write rendered template to a file\n* `--undefined`: Allow undefined variables to be used in templates (no error will be raised)\n\n* `--filters filters.py`: Load custom Jinja2 filters and tests from a Python file.\n    Will load all top-level functions and register them as filters.\n    This option can be used multiple times to import several files.\n* `--tests tests.py`: Load custom Jinja2 filters and tests from a Python file.\n* `--customize custom.py`: A Python file that implements hooks to fine-tune the j2cli behavior.\n    This is fairly advanced stuff, use it only if you really need to customize the way Jinja2 is initialized.\n    See [Customization](#customization) for more info.\n\nThere is some special behavior with environment variables:\n\n* When `data` is not provided (data is `-`), `--format` defaults to `env` and thus reads environment variables\n* When `--format=env`, it can read a special \"environment variables\" file made like this: `env \u003e /tmp/file.env`\n\n## Formats\n\n\n### env\nData input from environment variables.\n\nRender directly from the current environment variable values:\n\n    $ j2 config.j2\n\nOr alternatively, read the values from a dotenv file:\n\n```\nNGINX_HOSTNAME=localhost\nNGINX_WEBROOT=/var/www/project\nNGINX_LOGS=/var/log/nginx/\n```\n\nAnd render with:\n\n    $ j2 config.j2 data.env\n    $ env | j2 --format=env config.j2\n\nIf you're going to pipe a dotenv file into `j2`, you'll need to use \"-\" as the second argument to explicitly:\n\n    $ j2 config.j2 - \u003c data.env\n\n### ini\nINI data input format.\n\ndata.ini:\n\n```\n[nginx]\nhostname=localhost\nwebroot=/var/www/project\nlogs=/var/log/nginx/\n```\n\nUsage:\n\n    $ j2 config.j2 data.ini\n    $ cat data.ini | j2 --format=ini config.j2\n\n### json\nJSON data input format\n\ndata.json:\n\n```\n{\n    \"nginx\":{\n        \"hostname\": \"localhost\",\n        \"webroot\": \"/var/www/project\",\n        \"logs\": \"/var/log/nginx/\"\n    }\n}\n```\n\nUsage:\n\n    $ j2 config.j2 data.json\n    $ cat data.json | j2 --format=ini config.j2\n\n### yaml\nYAML data input format.\n\ndata.yaml:\n\n```\nnginx:\n  hostname: localhost\n  webroot: /var/www/project\n  logs: /var/log/nginx\n```\n\nUsage:\n\n    $ j2 config.j2 data.yml\n    $ cat data.yml | j2 --format=yaml config.j2\n\n\n\n\nExtras\n======\n\n## Filters\n\n\n### `docker_link(value, format='{addr}:{port}')`\nGiven a Docker Link environment variable value, format it into something else.\n\nThis first parses a Docker Link value like this:\n\n    DB_PORT=tcp://172.17.0.5:5432\n\nInto a dict:\n\n```python\n{\n  'proto': 'tcp',\n  'addr': '172.17.0.5',\n  'port': '5432'\n}\n```\n\nAnd then uses `format` to format it, where the default format is '{addr}:{port}'.\n\nMore info here: [Docker Links](https://docs.docker.com/userguide/dockerlinks/)\n\n### `env(varname, default=None)`\nUse an environment variable's value inside your template.\n\nThis filter is available even when your data source is something other that the environment.\n\nExample:\n\n```jinja2\nUser: {{ user_login }}\nPass: {{ \"USER_PASSWORD\"|env }}\n```\n\nYou can provide the default value:\n\n```jinja2\nPass: {{ \"USER_PASSWORD\"|env(\"-none-\") }}\n```\n\nFor your convenience, it's also available as a function:\n\n```jinja2\nUser: {{ user_login }}\nPass: {{ env(\"USER_PASSWORD\") }}\n```\n\nNotice that there must be quotes around the environment variable name\n\n\n\n\nCustomization\n=============\n\nj2cli now allows you to customize the way the application is initialized:\n\n* Pass additional keywords to Jinja2 environment\n* Modify the context before it's used for rendering\n* Register custom filters and tests\n\nThis is done through *hooks* that you implement in a customization file in Python language.\nJust plain functions at the module level.\n\nThe following hooks are available:\n\n* `j2_environment_params() -\u003e dict`: returns a `dict` of additional parameters for\n    [Jinja2 Environment](http://jinja.pocoo.org/docs/2.10/api/#jinja2.Environment).\n* `j2_environment(env: Environment) -\u003e Environment`: lets you customize the `Environment` object.\n* `alter_context(context: dict) -\u003e dict`: lets you modify the context variables that are going to be\n    used for template rendering. You can do all sorts of pre-processing here.\n* `extra_filters() -\u003e dict`: returns a `dict` with extra filters for Jinja2\n* `extra_tests() -\u003e dict`: returns a `dict` with extra tests for Jinja2\n\nAll of them are optional.\n\nThe example customization.py file for your reference:\n\n```python\n#\n# Example customize.py file for j2cli\n# Contains potional hooks that modify the way j2cli is initialized\n\n\ndef j2_environment_params():\n    \"\"\" Extra parameters for the Jinja2 Environment \"\"\"\n    # Jinja2 Environment configuration\n    # http://jinja.pocoo.org/docs/2.10/api/#jinja2.Environment\n    return dict(\n        # Just some examples\n\n        # Change block start/end strings\n        block_start_string='\u003c%',\n        block_end_string='%\u003e',\n        # Change variable strings\n        variable_start_string='\u003c\u003c',\n        variable_end_string='\u003e\u003e',\n        # Remove whitespace around blocks\n        trim_blocks=True,\n        lstrip_blocks=True,\n        # Enable line statements:\n        # http://jinja.pocoo.org/docs/2.10/templates/#line-statements\n        line_statement_prefix='#',\n        # Keep \\n at the end of a file\n        keep_trailing_newline=True,\n        # Enable custom extensions\n        # http://jinja.pocoo.org/docs/2.10/extensions/#jinja-extensions\n        extensions=('jinja2.ext.i18n',),\n    )\n\n\ndef j2_environment(env):\n    \"\"\" Modify Jinja2 environment\n\n    :param env: jinja2.environment.Environment\n    :rtype: jinja2.environment.Environment\n    \"\"\"\n    env.globals.update(\n        my_function=lambda v: 'my function says \"{}\"'.format(v)\n    )\n    return env\n\n\ndef alter_context(context):\n    \"\"\" Modify the context and return it \"\"\"\n    # An extra variable\n    context['ADD'] = '127'\n    return context\n\n\ndef extra_filters():\n    \"\"\" Declare some custom filters.\n\n        Returns: dict(name = function)\n    \"\"\"\n    return dict(\n        # Example: {{ var | parentheses }}\n        parentheses=lambda t: '(' + t + ')',\n    )\n\n\ndef extra_tests():\n    \"\"\" Declare some custom tests\n\n        Returns: dict(name = function)\n    \"\"\"\n    return dict(\n        # Example: {% if a|int is custom_odd %}odd{% endif %}\n        custom_odd=lambda n: True if (n % 2) else False\n    )\n\n#\n\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkolypto%2Fj2cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkolypto%2Fj2cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkolypto%2Fj2cli/lists"}