github.com/decred/politeia@v1.4.0/politeiawww/cmd/pictl/README.md (about)

     1  pictl
     2  ====
     3  
     4  pictl is a command line tool that allows you to interact with the politeiawww
     5  API and has been configured to be a pi (Decred's proposal system) client.
     6  
     7  # Available Commands
     8  You can view the available commands and application options by using the help
     9  flag.
    10  
    11      $ pictl -h 
    12  
    13  You can view details about a specific command by using the help command.
    14  
    15      $ pictl help <command>
    16  
    17  # Persisting Data Between Commands
    18  pictl stores  user identity data (the user's public/private key pair), session
    19  cookies, and CSRF tokens in the pictl directory.  This allows you to login with
    20  a user and use the same session data for subsequent commands.  The data is
    21  segmented by host, allowing you to login and interact with multiple hosts
    22  simultaneously.
    23  
    24  The location of the pictl directory varies based on your operating system.
    25  
    26  **macOS**
    27  
    28  `/Users/<username>/Library/Application Support/Pictl`
    29  
    30  **Windows**
    31  
    32  `C:\Users\<username>\AppData\Local\Pictl`
    33  
    34  **Ubuntu**
    35  
    36  `~/.pictl`
    37  
    38  # Setup Configuration File
    39  pictl has a configuration file that you can setup to make execution easier.
    40  You should create the configuration file under the following paths.
    41  
    42  **macOS**
    43  
    44  `/Users/<username>/Library/Application Support/Pictl/pictl.conf`
    45  
    46  **Windows**
    47  
    48  `C:\Users\<username>\AppData\Local\Pictl/pictl.conf`
    49  
    50  **Ubuntu**
    51  
    52  `~/.pictl/pictl.conf`
    53  
    54  If you're developing locally, you'll want to set the politeiawww host in the
    55  configuration file to your local politeiawww instance. The host defaults to
    56  `https://proposals.decred.org`.  Copy these lines into your `pictl.conf` file.
    57  `skipverify` is used to skip TLS certificate verification and should only be
    58  used when running politeia locally.
    59  
    60  ```
    61  host=https://127.0.0.1:4443
    62  skipverify=true
    63  ```
    64  
    65  # Example Usage
    66  
    67  ## Create a new user
    68  
    69      $ pictl usernew email@example.com username password --verify --paywall
    70  
    71  `--verify` and `--paywall` are options that can be used when running
    72  politeiawww on testnet to make the user registration process quicker.
    73  
    74  `--verify` will satisfy the email verification requirement for the user.
    75  
    76  `--paywall` will use the Decred testnet faucet to satisfy the user registration
    77  fee requirement. 
    78  
    79  **If you use the `--paywall` flag, you will still need to wait for block
    80  confirmations before you'll be allowed to submit proposals.**
    81  
    82  ## Login with the user
    83  
    84      $ pictl login email@example.com password
    85  
    86  ## Assign admin privileges and create proposal credits
    87  
    88  Proposal credits are required in order to submit a proposal. They are a spam
    89  prevention measure that would normally need to be purchased using DCR, but if
    90  you're running politeiawww locally, you can use the politeiawww_dbutil tool to
    91  add proposal credits to your account.  You'll also need to give your user admin
    92  privileges if you want to be able make proposals public and to start the
    93  proposal vote.
    94  
    95  **You need to stop politeiawww in order to run these commands.  You'll
    96  get a `resource temporarily unavailable` error if you don't.**
    97  
    98      $ politeiawww_dbutil -testnet -setadmin username true
    99      $ politeiawww_dbutil -testnet -addcredits username 50
   100  
   101  **Start politeiawww back up.**
   102  
   103  ## Submit a new proposal
   104  
   105  When submitting a proposal, you can either specify a markdown file or you can
   106  use the `--random` flag to have pictl generate a random proposal for you.
   107  
   108      $ pictl proposalnew --random
   109      {
   110        "files": [
   111          {
   112            "name": "index.md",
   113            "mime": "text/plain; charset=utf-8",
   114            "digest": "2a72cd797f164489f18628a84b81604d91cb3dd9e8217e3f12c6ba37ab6b7760",
   115            "payload": "S0gycmxiZUJiVmJ4bTR0OEhwRWpQZGxEQlpXdUl1QkR4RjU3cXNZZXpFZz0KUnJJRmtqM2RYaTEwQW9GekZaKzd3QW9HVk5LVzVRWkZWUzNYWi9jbnJTWT0KQmYrcDY4YXN4NE1PWFk1WHl2a1RLTm1QdlM1bjdUcjZNQ0p5ZWdtZm1UVT0KMVNyWFp6Smh6VDBGd29LYnppdStBMDdKNUtiQ1NOV1NwUmNMaW92L2I4ST0KNno2clpnWTVxemtPbGMxL1pPZ2pRV1NZbVdhdGgyT1BnQng5L1J6RHVxbz0KelNSRmNobDNvTS9QU0J1WUVuWmdrd3o2SG5HVjdiQytEUkZlMDBudUJGaz0KcHRuL2xoeTFlcTNpeHpEanBHVVMxSjVZVDFrVEtlMW9tcUxpRGNPSTRlcz0KOXdwempHcE9mb3p0ZEFXcHhwWU52THpDbGgvVU5rYTVCNjRCV01GcEdVMD0KOUpHZE05Nzd4SjJJTkFIZ2dGSjBKczhvUDVKb0JIQ1dsRTEzSzFtSmQvdz0KR3Z2eWdiVEsvakIybHBVbE41Q250SjlGWUdOQmY0TG5Idzl0a2FxYWVUZz0K"
   116          }
   117        ],
   118        "metadata": [
   119          {
   120            "hint": "proposalmetadata",
   121            "digest": "cd7e75c3df810965c48c3c03a47062a1f5bf7e4458b036380877d3c59e331b41",
   122            "payload": "eyJuYW1lIjoiMjI1ZDJiZTFiYWQ2ZWU0MiJ9"
   123          }
   124        ],
   125        "publickey": "72a1a0f19d6d76b9bbec069f5672fa9f22485961b1dffe8c570558e88168076a",
   126        "signature": "981711bbf6cf408859f5eeab71bc5ec5a3fb4a723d3c853ede20415c9a5db1f2fd53265f73d79389e54b3ef5e0e924d0b48dee5b380c90ed093a3adcd7dab708"
   127      }
   128      {
   129        "timestamp": 1602104519,
   130        "censorshiprecord": {
   131          "token": "98daf0732ac3006c0000",
   132          "merkle": "928b9cede1846ba542a81d9a7968baff2b7f7cc4d80f52957746be8f6c3869de",
   133          "signature": "e30fc5332197f7b8f8fb8f73228a79295c7328d75aff10c123eb00d18e29fbd1a3fb96839f738c1ba19169246b018be389b8898afa1f4466b11a69c036187407"
   134        }
   135      }
   136  
   137  Proposals are identified by their censorship record token in all other
   138  commands. The censorship record token of the proposal example shown above is
   139  `98daf0732ac3006c0000`.
   140  
   141  ## Make a proposal public (admin privileges required)
   142  
   143  The proposal must first be vetted by an admin and have the proposal status set
   144  to public before it will be publicly viewable.
   145  
   146      $ pictl proposalsetstatus [token] public
   147  
   148  Now that the proposal status has been made public, any user can comment on the
   149  proposal. Once the proposal author feels the discussion period was sufficient,
   150  they can authorize the voting period to start.
   151  
   152  ## Authorize the voting period on a proposal (must be author)
   153  
   154  Before an admin can start the voting period on a proposal the author must
   155  authorize the vote.
   156  
   157      $ pictl voteauthorize [token]
   158  
   159  ## Start a proposal vote (admin privileges required)
   160  
   161  Once a proposal vote has been authorized by the author, an admin can start the
   162  voting period at any point.
   163  
   164      $ pictl votestart [token]
   165  
   166  ## Voting on a proposal
   167  
   168  Voting on a proposal can be done using either `pictl` or `politeiavoter`.
   169  `pictl` is for development uses only. `politeiavoter` should be used when
   170  voting on production proposals.
   171  
   172  ### politeiavoter
   173  
   174  See the [politeiavoter](https://github.com/decred/politeia/tree/master/politeiawww/cmd/politeiavoter/)
   175  documentation for more information on using `politeiavoter`.
   176  
   177  ### pictl
   178  
   179  You can vote on testnet proposals using `pictl` if you have the following
   180  setup:
   181  - dcrwallet is running locally on testnet and on the default port.
   182  - A dcrwallet client cert has been setup for `pictl` using the instructions
   183    in the `Dcrwallet Authentication` section of this README. 
   184  
   185  Cast a ballot of DCR ticket votes.
   186  
   187      $ pictl castballot [token] [voteID]
   188  
   189  # Dcrwallet Authentication
   190  
   191  Voting requires access to wallet GRPC. Therefore this tool needs the wallet's
   192  server certificate to authenticate the server, as well as a local client
   193  keypair to authenticate the client to `dcrwallet`.  The server certificate by
   194  default will be found in `~/.dcrwallet/rpc.cert`, and this can be modified to
   195  another path using the `--walletgrpccert` flag.  Client certs can be generated
   196  using [`gencerts`](https://github.com/decred/dcrd/blob/master/cmd/gencerts/)
   197  and `pictl` will read `client.pem` and `client-key.pem` from its
   198  application directory by default.  The certificate (`client.pem`) must be
   199  appended to `~/.dcrwallet/clients.pem` in order for `dcrwallet` to trust the
   200  client.
   201  
   202  For example:
   203  
   204  ```
   205  $ gencerts ~/.pictl/client{,-key}.pem
   206  $ cat ~/.pictl/client.pem >> ~/.dcrwallet/clients.pem
   207  ```
   208  
   209  # Dev commands
   210  
   211  `pictl` comes with commands that are useful during development. 
   212  
   213  `seedproposals` seeds the backend with users, proposals, comments, and comment
   214  upvotes/downvotes.
   215  
   216      $ pictl seedproposals email@example.com password
   217  
   218  `votetestsetup` and `votetest` can be used to setup a batch of proposal votes
   219  then to vote on them using your eligible tickets.
   220  
   221      $ pictl votetestsetup email@example.com password
   222      $ pictl votetest
   223  
   224  Print the help message, `pictl -h`, to see a full list of these dev commands.